Build Your First Kwyll Game: Gem Patrol

Choose a folder where you can keep the project and any copies you make while following the tutorial.

Before adding anything, take a moment to notice the main editors in Kwyll. We will use the Screens, Rooms, and Map editors in this milestone. Later, we will also spend time in the Object and Logic editors.

A Screen controls what the player sees around the game itself. It can contain the game window, a tilemap used as a border or background, and Instruments that display values such as a score or number of lives.

This makes the game window 256 pixels wide and 176 pixels high, leaving two 8-pixel rows for the status area on a 256-by-192-pixel Screen.

In the Screen Layout, the blue rectangle represents the game window. Drag it down by two character rows to leave a narrow status area above it. Its final position should be X 0, Y 2 in screen cells.

Leave enough space above the game window for a number showing how many gems have been collected.

Rooms use a tilemap for their background. A tile is a small reusable picture; on the ZX Spectrum target each tile is 8 by 8 pixels. Tiles can also carry collision and Type information that affects the game.

For this tutorial, keep the artwork simple. Clear shapes make it easier to concentrate on how the project is assembled.

Create these four tiles:

A Room Type defines a reusable space. It contains a tilemap and can also contain objects, markers, variables, and Logic. A Room Type does not appear in the game until it is placed on the Map as a Location.

Keep the opening at least as wide as the Player sprite that you intend to draw. A two-tile-wide opening is a safe starting point for a 16-pixel-wide Player.

The same Yard will later be used for both Entrance Yard and Upper Yard. Giving it a single bottom opening means both uses of the Room Type have the same connection pattern, and neither produces an opening that leads nowhere.

The top opening will connect to Entrance Yard and the right opening to the Store Room.

Leave a reasonably open space in the middle. We will place a horizontally moving enemy there in a later milestone.

Do not make the passages too narrow. The Store Room will later contain a vertically moving enemy, and the Player needs enough space to avoid it.

Open the Map editor. The asset list contains the three Room Types that we have created.

Drag a Room Type from the asset list onto the Map to create a Location. We need four Locations:

Arrange the Locations so that their matching room openings meet:

Take a moment to compare Entrance Yard and Upper Yard. They are two Locations, but both refer to the same Yard Room Type. If you return to the Rooms editor and change the Yard tilemap, both Locations will use the updated design.

Later, each Yard Location will nevertheless remember its own collected gems. That works because variable values associated with Room Logic are stored on the individual Location.

Save the project and open Preview. Start the game.

You should see:

Nothing moves yet because the project does not contain a Player Object. That is exactly where we expect to be.

Objects use Sprites rather than Tiles. Tiles are fixed at 8 by 8 pixels, while a Sprite can be larger and can include a mask that allows the room background to show around its shape.

The artwork does not need to be elaborate. A clear body, head, and one small directional detail are enough. We will use a single image for now so that we can concentrate on movement.

The Sprite is only the picture. An Object Type combines one or more Sprites with animations, default drawing properties, and Logic.

This tutorial uses one animation frame for the initial controller. Directional animations can be added later without changing the movement Logic.

Variables give Logic somewhere to store numbers. Every instance of an Object Type receives its own values for the variables defined by that type.

Open the Player’s Logic tab. In the Variables panel, add these three variables:

Enable Initialised for each variable. The initial values will be set on the Player Object Instance after we place it on the Map.

facing_x = 0 and facing_y = 1 mean that the Player begins facing down. These two variables will be used when we add projectiles.

The Player Object Type defines what a Player looks like and what every Player can do. We still need an Object Instance that actually exists in the game.

The Player flag tells Kwyll that this object controls the current Location. When it crosses an open edge, Kwyll looks for a neighbouring Location on the Map and moves the game there.

The Collide Bg flag makes movement respect the collision settings on our Wall tile. Visible draws the Sprite, while Active allows the instance to take part in object interactions later.

Return to the Player Object Type and open its Logic tab.

Kwyll Logic is made from Nodes. White connections control the order in which actions happen. Coloured value connections carry numbers or references between Nodes.

Right-click an empty part of the graph, or press kbd:[Shift+A], to open the node menu. Typing part of a Node’s name is usually the quickest way to find it.

When we add projectiles, the game will need to know which way the Player last faced. We will record that now while the controller values are already familiar.

Create a separate Always flow. Add another Controller Input Node using Mode Pressed, with the same directional values as before.

Build a chain of four If Nodes:

Connect the second Always trigger to the first If. Connect each False flow to the next test. Each True branch ends after setting both variables.

Checking the directions in this order also gives diagonal input a predictable facing direction: horizontal input takes priority over vertical input.

Save and run Preview again.

The Player should appear at the corresponding edge of the new Location and continue to respond to the controller. No explicit change-room Logic is required: the Player flag and the arrangement of Locations on the Map handle this automatically.

Also test the closed edges. Walking into a Wall should stop the Player rather than changing Location.

Keep the effect brief. It may play several times in quick succession while the Player moves through a group of gems.

Open the Player Object Type and return to its Logic graph. Find an empty area away from the movement flows.

The Gem tile was given Type 1 in Milestone 1. Touch Tile runs when the Player’s bounding rectangle touches a tile with a non-zero Type, and the If ensures that this flow handles only gems.

The gems in our rooms were painted over Decorative floor areas, so replacing a gem with tile 3 reveals the surface that was visually beneath it. If your Decorative floor has a different index, use that index instead.

The Gem disappears immediately because its tilemap cell is replaced with Decorative floor. The replacement also prevents the collection flow from running again on the following update: Floor has Type 0, so Touch Tile no longer triggers for that cell.

Save and test the game now. Touching a gem should play the sound and replace the gem with Floor. The counter will still show 0, and the gem will return after leaving and re-entering the Location. Both behaviours are expected at this stage.

We now need to tell two other parts of the project what happened:

We will use message ID 1 to mean “a gem was collected” in all four Logic areas.

Message Location needs an explicit Location reference because this flow is running on the Player Object, not in Room Logic. Current Location provides the Location the Player is presently exploring.

The complete white flow should now be:

Open the Game Logic editor.

Each collection message sends 1 in P1, so Change Variable increases the total by one.

Still in Game Logic:

The message is sent after the variable changes, so P1 contains the new total.

Open the Game Screen and select its Logic tab.

Screen Logic does not own the total. It simply displays the value supplied by Game Logic.

Save and test again. Collect two gems and check that GemCount changes from 0 to 1, then to 2.

We will build the persistence Logic on Yard, then let the other two Room Types share it.

Open the Yard Room Type and select its Logic tab. Add these initialised variables:

Set every initial value to 0.

Each gem requires two array entries: one for X and one for Y. An array length of 16 therefore has room for eight gems in one Location, which is enough for the rooms in this tutorial.

In Yard Logic:

The result is the first free array index. For example, if two gems have already been collected, num_collected is 2 and the next pair begins at index 4.

This stores the X coordinate.

This stores the Y coordinate in the following array entry.

The count is increased only after both coordinates have been stored.

Still in Yard Logic:

The Repeat body runs once for every remembered gem.

This reads the stored X coordinate.

This reads the stored Y coordinate.

Leave the Flow Out of Set Tile unconnected. When the body ends, Repeat advances its Index and begins the next iteration.

The persistence flow does not depend on the layout of Yard. Corridor and Store Room can reuse it.

All three Room Types now use the same Room Logic and variable declarations. Each Location still receives its own values. In particular, Entrance Yard and Upper Yard share the Yard Room Type and its Logic, but their collected_positions arrays remain independent.

Open the Map and inspect the properties of all four Locations. Confirm that each has:

Save and run Preview. Use this test route:

The total in GemCount should continue increasing across all Locations.

In Preview’s Data panel, expand the Locations and compare num_collected for Entrance Yard and Upper Yard. Their different values make the per-Location state visible.

Make the Enemy visually distinct from the Player. A pointed, angular, or one-eyed design works well at this size.

Open the Enemy’s Logic tab and add three initialised integer variables:

The Logic will multiply each direction by speed. A zero direction means no movement on that axis.

The calculation is a smaller version of the Player movement graph. There is no Controller Input because the Enemy gets its direction from variables.

This produces the requested new X position.

This produces the requested new Y position.

The Enemy instances will have Collide Bg enabled. When Move Object tries to move one into a solid Wall tile, Kwyll prevents the movement and runs the Enemy’s Collided trigger.

We will reverse both direction variables. One of them is zero for each Enemy, and zero multiplied by -1 remains zero.

The Sides output of Collided is not needed for this simple patrol. A more advanced controller could inspect it and reverse only the axis that hit a wall.

Open the Corridor Room Type and select its Layout tab.

This is a Room Object. It exists only while Stone Corridor—the Location using the Corridor Room Type—is current.

Do not place it directly in the exit leading to the Store Room. Room Objects do not use the Player’s automatic Map navigation, so the patrol should be bounded by walls inside its Room Type.

Select the Store Room Room Type.

This second instance uses the same Enemy Logic but moves vertically because its variable values are different.

Save and run Preview.

The Enemy should be recreated from its Room Object data when its Location becomes active again. It may restart from its initial position and direction; unlike collected-gem state, we are not recording patrol progress.

The Enemies do not damage the Player yet. They can overlap it because we have not configured object intersection behaviour. That will be added alongside projectiles in the next milestone.

In Preview’s Data panel, expand the current Room’s Objects section. The live Enemy instance should show its position and its speed, move_x, and move_y values. Watch the appropriate direction change between 1 and -1 when it reaches a wall.

The default Kwyll project already contains a Fire Beep FX that is suitable for the Projectile. We will reuse it rather than creating another one.

The Projectile can be smaller than the Player and Enemy.

Add these initialised variables to Projectile Logic:

All three values begin at zero. Dynamic Objects do not take the configured instance defaults used by placed Map and Room Objects, so the Player will send the movement values immediately after spawning the Projectile.

In Projectile Logic:

The Player will use message ID 1 when initialising a newly spawned Projectile. P1 carries facing_x, while P2 carries facing_y.

Build a movement flow in Projectile Logic:

This is the same movement pattern used by the Enemy. Reusing a familiar pattern is often easier and safer than inventing a different solution for every Object Type.

Add a Collided trigger and connect it directly to a Kill Object Node. Leave Ref unconnected so that the current Projectile is removed.

Kill Object works here because the Projectile was created dynamically. It cannot remove the Enemy Room Objects.

A Projectile might travel through an open exit instead of hitting a wall. We do not want unseen Dynamic Objects to accumulate.

The Projectile continues to exist while it is on the current Screen. As soon as its position is outside, it is removed.

Kwyll uses intersection layers to avoid testing every object against every other object. We only need Projectiles to test against Enemies.

Open the Enemy instance properties in both Corridor and Store Room. For each Enemy:

The two Enemy instances must use the same layer configuration.

There is no separate Intersect Objects flag on an Object Instance. Whether an intersection is registered is determined by the On Layers and Checks Layers settings.

Open Player Logic and find another empty area.

Using Just Pressed creates one Projectile for each press. Using Pressed would attempt to create a new Projectile on every update while Fire was held.

A new project defaults Max Dynamic Objects to 0. If it remains zero, every Spawn Object attempt follows the Fail output and no Projectile appears.

The Projectile begins at the Player’s map position. Because we will configure it to check only the Enemy layer, overlapping the Player at the moment of creation does not count as a hit.

Spawn Object has Success and Fail flows. The Fail flow runs if the project has reached its Max Dynamic Objects limit. We can leave Fail unconnected in this introductory game; a larger project could play a different sound or reuse an existing Projectile.

Dynamic Objects are created Visible and Active, but the Projectile also needs background collision and intersection settings.

Use the three-state flag controls carefully: On explicitly enables a flag, Off disables it, and Leave preserves its existing value.

The complete success path now creates the Projectile, configures its flags and layers, and tells it which way to move.

Save and test before adding Enemy hits.

The Player should fire one Projectile per press. Test all four facing directions. Each Projectile should travel until it hits a wall or leaves through an exit, then disappear.

In Preview’s Data panel, expand Dynamic Objects while a Projectile is visible. Its direction values should match the Player’s facing values.

In Projectile Logic:

This protects the combat flow from reacting to any other Object Type that might later share an intersection layer.

Message ID 2 means “the Enemy was hit”. The Projectile tells the Enemy first, then removes itself.

Room Objects cannot be removed with Kill Object; that Node is specifically for Dynamic Objects. Instead, the Enemy will respond to message ID 2 by turning off the flags that make it visible and active.

Open Enemy Logic:

Once inactive and invisible, the Room Object behaves as a defeated Enemy.

Save and run Preview.

The Enemy should remain defeated. A Room Object is stored in the Room Type’s definition, and changes to its flags persist until the game is reset. Leaving and re-entering a Location does not create a fresh copy of it.

This also matters when reusing Room Types. A Room Object belongs to the Room Type, not to an individual Location. If two Locations use the same Room Type, disabling an Enemy this way makes it disappear from both Locations.

If your game should restore its Enemies whenever the player enters a room, add a Room Entered trigger to the room’s Logic and connect it to a Set Object Flags Node for each Enemy. Set Visible and Active to On, and restore any other flags or variables that the Enemy needs. If reused Locations should remember separate defeated states, store that state in per-Location variables, as we did for collected gems, and use Room Entered to apply the correct state.

Save the project, open Preview, and play from Entrance Yard to Store Room. Try to test features together rather than one at a time:

If something goes wrong, use Preview’s Data and Debugger panels to inspect the current values and active Objects. Testing after each small change is usually faster than trying to diagnose several changes at once.

Gem Patrol is deliberately small, but it uses the main ideas that larger Kwyll projects are built from:

The gem system also demonstrates an especially useful principle: store lasting game state separately from what is currently drawn. The tile changes immediately when collected, while a per-Location variable records that change so the room can restore the correct state when the player returns.

This project is a template rather than a complete game. Good next steps include:

Make one change at a time and test it. Reusing a familiar project while experimenting is one of the easiest ways to learn what Kwyll’s Nodes and editors can do.