Documentation

⚠️ Warning: Gameeky is still in early stages of development and therefore things are subject to change.

📝 Note: This document is not an exhaustive tutorial on everything Gameeky can do, but should provide enough directions to get started.

Topics

  1. Introduction
  2. Installation
  3. Thematic packs
  4. Overview
  5. The launcher
  6. The player
  7. Cooperative game play
  8. The scene editor
  9. The entity editor
  10. The code editor and LOGO-like code
  11. Plugins

Introduction

Gameeky lets young learners and educators create and explore cooperative games and learning experiences. More specifically:

📝 Note: This is a learning tool in the shape of a game engine. It’s not a professional game engine. If you’re looking for a tool to create professional video games, please consider the Godot game engine.

Installation

The recommended installation method is through the software center of the system, e.g., GNOME Software. Search for Gameeky and install it. Alternatively, it can also be installed from Flathub. Similarly, search for Gameeky and follow the website instructions.

Lastly, it can also be installed from the terminal:

flatpak --user install flathub dev.tchx84.Gameeky

Thematic packs

Gameeky provides packs of predefined building blocks for different interests, e.g., a farming role playing game set in a medieval fantasy world. A thematic pack contains:

These building blocks can be reused to create custom scenes, new games and many learning materials.

The recommended installation method is through the software center of the system, e.g., GNOME Software. Thematic packs are offered as addons from the software center page. Alternatively, it can also be installed from Flathub. Similarly, thematic packs are offered as addons from the website. Select the addon and follow the website instructions.

Lastly, packs can also be installed from the terminal:

flatpak --user remote-ls flathub | grep dev.tchx84.Gameeky.ThematicPack
flatpak --user install flathub dev.tchx84.Gameeky.ThematicPack.FreedomValley

Overview

The Gameeky package provides five main components:

  1. The launcher is the main component where all thematic packs and projects can be found and launched from.
  2. The player is where games can be played and joined.
  3. The scene editor is where scenes can be created and edited.
  4. The entity editor is where entities can be created and edited.
  5. The code editor is where the LOGO-like experience can be had.

The launcher

The launcher serves as the Gameeky starting point. It provides an easy way to manage thematic packs installed as addons and projects located under the ~/Gameeky directory. The manager supports all the basic management operations:

Sharing projects

The launcher provides a simple way to share projects. To export a project, follow these steps:

  1. From the launcher, click on the Options button of the project and select the Export option.
  2. Follow the dialog instructions.

To import a project, follow these steps:

  1. From the launcher, go to the menu and select the Import option.
  2. Follow the dialog instructions.

The player

The player provides a visual representation of the game world and the means to interact with that world.

To start a game, click on the Play button of the project from the launcher. This will start the default scene for that project. Every thematic pack and project comes with a default scene. To play other scenes from the same project, follow these steps:

  1. From the launcher, click on the Options button of the project and select the Play option.
  2. From the player, go to the menu and select the New option.
  3. From the creation dialog, select the scene file and click on the Create button.

In-game screen elements

Once in the game, the scene takes most of the screen but there are other elements as well.

The HUD is an interface placed at the bottom center of the screen. This element is used to visualize the user’s character stats. It’s composed of the following parts:

Another element is the dialogue viewer. This viewer is placed at the bottom of the screen and it’s used to display in-game dialogues, e.g., a message from a game character or the narrator. It’s composed of the following parts:

Controls

Once in the game, the user’s character can be controlled with two methods:

Actions

The user’s character can perform multiple actions to interact with the game world:

Save files

The state of the game can be saved at any moment and restored later. Save files are full copies of the scene and therefore regular scene files.

  1. To save the state of the game, go to the menu and select the Save As… option.
  2. To restore the state of the game, follow the same steps described above to open an scene.

Cooperative game play

Gameeky was designed from the ground up to create and share cooperative experiences. All the games created with it can be played cooperatively. There are no special requirements. Although there’s no theoretical limit as for how many users can join a cooperative game, there are technical limitations. E.g., limited computing resources.

To start a cooperative game, follow these steps:

  1. From the launcher, click on the Options button of the project and select the Play option.
  2. From the player, go to the menu and select the New option.
  3. From the creation dialog, increase the number of participants and then click on the Create button.

To join a cooperative game:

  1. From the launcher, click on the Options button of the project and select the Play option.
  2. From the player, go to the menu and select the Join option.
  3. From the join dialog, specify the IP address of the user who started the cooperative game and click on the Join button.

📝 Note: All the users joining a cooperative game must have a copy of the same thematic pack or project.

📝 Note: Custom scenes created from thematic packs don’t need to be shared. The scene is automatically shared during game play, as long as all users share the same thematic pack.

📝 Note: Users can join a session as any entity defined in the thematic pack, e.g., as a tree or a rock. To do this, expand the Advance section of the creation or join dialog and select a different Entity Type.

The scene editor

The scene editor lets users create and modify game worlds. It serves as the initial and simplest form of no-code creation experience in Gameeky.

To edit an existing Scene, click on the Edit button of the project from the launcher. To create a new scene it’s recommended to start off an existing project such as a thematic pack. Follow these steps to add a new Scene:

  1. From the launcher, click on the Options button of the project and select the Edit option.
  2. From the scene editor, go to the menu and select the New option.

📝 Note: Thematic packs can’t be modified. Therefore, an editable copy must be created. From the thematic pack options menu, select the Copy option.

Concepts

A scene is a collection of entities arranged in a tiles grid. The basic properties of a scene are:

Workflow

The scene editing workflow resembles one of a painting tool. Entities are painted and removed to and from the scene. The basic steps to edit a scene are the following:

  1. To add entities to the scene, select an entity from the left panel and place it on the scene by clicking on a tile in the grid.
  2. To remove entities from the scene, select the Remove tool from the left and then click on the entity tile in the grid.
  3. Although entities come with predefined properties and behaviors, particular entities in the scene can be customized. Select the Edit tool from the left panel and then click on the entity tile in the grid.
  4. To test the scene, go to the menu and select the Try It option.

Additionally, the scene editor provides helpers to make things easier such as:

Tips and tricks

For an improved experience, try the following tips and tricks:

The entity editor

The entity editor lets users create and modify game objects and creatures. It provides a deeper no-code creation experience, as it requires understanding the underlying systems of Gameeky.

Before creating a new entity from scratch, it’s recommended to inspect existing entities from thematic packs. So, to inspect an existing entity follow these steps:

  1. From the scene editor, right-click on an entity in the left panel.
  2. Select the Edit option from the menu.

To create a new entity:

  1. From the scene editor, right-click anywhere in the left panel.
  2. Select the Add option from the menu.

Concepts

Entities represent everything that can exist in the game, e.g., the grass, the user’s character, a light source, the background music and even the game logic. An entity is composed of three parts:

  1. Game logic properties.
  2. Graphics.
  3. Sounds.

Game logic properties

These properties determine how entities behave and interact with other entities, e.g., different combinations of these properties will determine whether an entity is acting as a static stone or a living foe.

Although there are two dozen properties, a few of these require special attention here:

📝 Note: When creating a new thematic pack assume that the entity with identifier number 1 will be assigned to the user’s character in the game.

Graphics

Entities are represented on the screen through 2D graphics, which can be static or animated.

These graphics are assigned to specific combinations of state and direction, e.g., a specific animation will be rendered when an entity is Moving to the West, while another animation will be rendered when the same entity is Idling to the South.

All entities must provide a Default graphic, e.g., to visualize it on the scene editor or debug plugins.

Sounds

Similarly to graphics, entities can emit sounds when in specific states, e.g., footsteps sound is played when the entity is Moving. Directions don’t matter here.

There aren’t Default sounds, as sounds are optional.

Workflow

The entity creation workflow is similar to filling a form or a template. The most basic entity is created with the following steps:

  1. Under the Game tab, start setting the values from top to bottom. Note that all properties provide their own defaults. Only the identifier is mandatory. Setting a name is recommended so that it’s easier to find the entity on the scene editor.
  2. Under the Graphics tab, click on the Add button to create the first and default animation. Leave both State and Direction to Default. Expand the Details section of the default animation to select an image. Click on the View button to inspect the selected image.
  3. Save the entity and use it from the scene editor.

Tips and tricks

For an improved experience, try the following tips and tricks:

The code editor and LOGO-like code

Having support for cooperative game play opens the door for cooperators that can be controlled with code. To achieve this, Gameeky provides a small library that enables users to control a single Entity using Python, in a LOGO-like experience.

Workflow

Follow these steps to start a cooperative game:

  1. From the launcher, click on the Options button of the project and select the Play option.
  2. From the player, go to the menu and select the New option.
  3. From the creation dialog, increased the number of participants and then click on the Create button.

To join the game with code, these steps must be followed:

  1. From the launcher, click on the Options button of the project and select the Play option.
  2. From the player, go to the menu and select the Join With Code option.
  3. Write Python code that uses the Gameeky library, see examples below.
  4. Click on the Play button.

Examples

Join and leave a game:

from gameeky.library import Game

game = Game()
game.join()
game.quit()

Perform actions:

from gameeky.library import Game, Direction

game = Game()
game.join()
game.update()

game.idle(time=1000)
game.move(Direction.EAST, time=1000)
game.move(Direction.WEST, time=1000)
game.take(time=1000)
game.use(time=1000)
game.drop(time=1000)
game.interact(time=1000)

game.quit()

Inspect the position and basic properties of the user’s character entity:

from gameeky.library import Game

game = Game()
game.join()
game.update()

print(game.entity.position.x, game.entity.position.y)

game.quit()

Inspect the state of the scene:

from gameeky.library import Game

game = Game()
game.join()
game.update()

for entity in game.scene.entities:
    print(entity.position.x, entity.position.y)

game.quit()

📝 Note: Cooperators can only see their immediate surroundings from the scene, not the full scene.

Inspect the advance stats of the user’s character entity:

from gameeky.library import Game

game = Game()
game.join()
game.update()

print(game.stats.durability, game.stats.stamina, game.stats.held)

game.quit()

Tips and tricks

For an improved experience, try the following tips and tricks:

Plugins

Actuators can modify the behavior of an entity. A single entity can use multiple actuators to model more complex behaviors. Although there’s a wide range of predefined actuators, the end result is limited when compared to actual code.

Therefore, Gameeky provides support for user-created actuators to go beyond what the predefined actuators can do.

Concepts

There are three types of actuators:

  1. Regular actuators enact on each tick of the scene, e.g., to move the entity to a random location on each tick.
  2. Activatable actuators enact only in fixed time intervals or when explicitly activated by another entity, e.g., to spawn a new foe to the scene every five seconds.
  3. Interactable actuators enact when other entities interact with its entity, e.g., to teleport an entity to a different location when that entity interacts with a portal.

All actuators use their own entity game properties to modify their behavior:

Workflow

To create a new actuator, follow the steps:

  1. Open a new document in a text editor.
  2. Write an actuator class, see examples below.
  3. Save the new document to ~/Gameeky/PROJECT_NAME/actuators/ACTUATOR_NAME.py
  4. From the entity editor, go under the Game tab to the actuators section.
  5. A new option called ACTUATOR_NAME will be displayed along with the predefined actuators.
  6. Select it and save the entity to disk.

📝 Note: User-created actuators can also be accessed from the scene editor when customizing specific entities.

Examples

A minimal actuator class:

from gameeky.plugins import Actuator as Plugin

class Actuator(Plugin):
    def tick(self) -> None:
        pass

Inspect the entity:

from gameeky.plugins import Actuator as Plugin

class Actuator(Plugin):
    def tick(self) -> None:
        print(self.entity.name)

Perform an action on the entity:

from gameeky.plugins import Actuator as Plugin
from gameeky.common.definitions import Action, Direction

class Actuator(Plugin):
    def tick(self) -> None:
        self.entity.perform(Action.MOVE, Direction.SOUTH)

Send a dialogue to the entity:

from gameeky.plugins import Actuator as Plugin

class Actuator(Plugin):
    def tick(self) -> None:
        self.entity.tell("Hello...")

Inspect all the other entities sitting right in front of the entity:

from gameeky.plugins import Actuator as Plugin

class Actuator(Plugin):
    def tick(self) -> None:
        for entity in self.entity.obstacles:
            print(entity.name)

Inspect all the other entities that share the same position as the entity:

from gameeky.plugins import Actuator as Plugin

class Actuator(Plugin):
    def tick(self) -> None:
        for entity in self.entity.surfaces:
            print(entity.name)

Inspect all the other entities that surround the entity:

from gameeky.plugins import Actuator as Plugin

class Actuator(Plugin):
    def tick(self) -> None:
        for entity in self.entity.surroundings:
            print(entity.name)

📝 Note: The surroundings method takes into account the Radius property of the entity.

Inspect all entities in the scene, that are not static:

from gameeky.plugins import Actuator as Plugin

class Actuator(Plugin):
    def tick(self) -> None:
        for entity in self.entity.scene.mutables:
            print(entity.name)

Inspect all entities that are controlled by users:

from gameeky.plugins import Actuator as Plugin

class Actuator(Plugin):
    def tick(self) -> None:
        for entity in self.entity.scene.playables:
            print(entity.name)

Create an actuator that enacts every five seconds:

from gameeky.plugins import Actuator as Plugin

class Actuator(Plugin):
    activatable = True

    def tick(self) -> None:
        if not self.ready:
            return

        print("Activated...")

        super().tick()

📝 Note: The ready property takes into account the Rate property of the entity.

Create an actuator that enacts only when interacted by users:

from gameeky.plugins import Actuator as Plugin

class Actuator(Plugin):
    interactable = True

    def prepare(self, interactee: "Entity") -> bool:
        if interactee.playable is False:
            return False

        return super().prepare(interactee)

    def tick(self) -> None:
        if self.interactee is None:
            return

        print(f"Interacted with {self._interactee.name}")

        super().tick()

Fore more complex examples check Gameeky’s predefined actuators directory.

Tips and tricks

For an improved experience, try the following tips and tricks: