Map creating

Yalk Map Creation Guide

This document describes how to build a map for Yalk and export it as a .pck file with the JKJuice addon.

1. Requirements

• Godot 4.7.x.
• A copy of the Yalk project, so the map can be tested with the actual player, collision and item prefabs.
• The JKJuice addon. The Addon just a exporter tool.

2. Make project

• Open godot and make new project
• Extract JKJuice to res://addons/, the resulting layout should look like this:

YourProject/
├── addons/
│   └── jkjuice/
│       ├── plugin.cfg
│       └── jkjuice.gd
└── project.godot

• Open Project -> Project Settings -> Plugins and enable JKJuice.
• Confirm that Project -> Tools -> Export Yalk Map... appears.

3. Required project layout

JKJuice expects these exact paths in the Yalk project:

Project/
├── map.tscn
├── manifest.json
├── textures/
|   ├── *.jpg
│   └── *.png
└── addons/
    └── jkjuice/

• map.tscn is the map scene that will be exported.
• textures/ contains the map's raster image assets. Subdirectories are allowed.
• manifest.json describes the supported game version and player-count range.

Yalk's runtime map loader requires manifest.json, so include it in every map you intend to distribute.

4. Map building

Geometry and collision

Use StaticBody2D nodes with CollisionShape2D children for solid floors, walls and platforms. Make sure the collision shape follows the visible geometry and that spawn markers are not inside walls, floors or other solid objects.

For one-way platforms, configure the collision shape/body as one-way and test dropping through it with the in-game S key action. Test the map with an actual player character in game.

Spawn points

Add a node named exactly Spawns somewhere below the map root. Its direct children must be Node2D nodes, Marker2D is a good choice.

Please, name it like Spawn1, Spawn2, etc. Add enough spawn points for the maximum number of players in your manifest. If every point is already claimed, the game falls back to a small offset around one of the existing points, so overlapping spawn positions should still be avoided.

If Spawns or its valid child markers are missing, the player spawn position falls back to (0, 0). Always include spawn markers in a published map.

5. Optional: place Yalk prefab items by reference

The map loader supports reference markers for items that already exist in the Yalk project. This is useful for placing a box, soda can or another built-in prefab without copying that prefab into the map pack.

1. Add a Node2D (or a subclass such as Marker2D) at the desired item position.
2. Give its node name Reference somewhere in the name, for example ReferenceBox.
3. In the Inspector, add metadata string named id (lowercase) or ID and set it to the prefab identifier/path (example: items/trash_canidk), don't use res:// or .tscn. Also, all yalk prefabs located in YalkSource/prefabs/, so please also don't write path with /prefabs/.
4. The loader will instance the matching scene at the marker's transform.

6. Create manifest.json

Template:

{
  "required_game_version": "0.1",
  "players": {
    "min_count": 2,
    "max_count": 8
  }
}

Field	Type	Meaning
required_game_version	String	Minimum Yalk version required by the map. The current yalk version is 0.1.
players.min_count	Integer	Smallest supported number of connected players. Must be at least 1.
players.max_count	Integer	Largest supported number of connected players. Must be greater than or equal to min_count.

7. Export the map

Before exporting:

1. Save map.tscn.
2. Save manifest.json.
3. Make sure all map textures are inside res://textures/.
4. Let Godot finish importing newly added or changed textures. The exporter reads the .import metadata and imported texture cache when those files exist.
5. Check that the map scene opens and runs in the editor.

Then:

1. Open Project -> Tools -> Export Yalk Map....
2. Choose the destination and filename for the .pck file.
3. Use a clear, unique filename such as warehouse.pck for example.
4. Wait for the output panel to report Export completed successfully. The filename without .pck becomes the map's internal name. For example, exporting warehouse.pck creates paths inside the pack under:

├── map.tscn
├── manifest.json
└── textures/
    └── ...

The exporter prints the packed files and total count to the Godot output panel. If the manifest is missing, the exporter can still create a pack, but Yalk will reject that pack at runtime.

8. Install and test a map pack

Yalk looks for .pck map files in these locations:

Location	Used when
res://maps/	Project/editor maps and maps bundled into the game project.
user://maps/	User-installed maps. The game creates this directory automatically.
maps/ beside the game executable	External maps in a non-editor build.

For a distributed build, create a maps directory beside the game executable and place the .pck files there, or install them into the game's user://maps/ directory.

Troubleshooting

if map not appear in rotation, it mean that you dont make a map using right way. If you still not understand, decompile res://maps/kebabka.pck from yalk source code to see how i made it.