Configuration (game.toml)

Your app’s root config file is game.toml in the app directory. It typically defines [Game] (name, version, description), [Window] (size, fullscreen, design size, scale mode), and optionally [Physics] for tag layers, collision layers, and the collision matrix used by raycasts and physics.

Physics layers and collision matrix

The optional [Physics] section in game.toml defines tag layers, collision layers, and a collision matrix. These are used for raycasts and physics (e.g. which objects can collide with which).

tag_layers and collision_layers

• tag_layers and collision_layers are arrays of names (e.g. ["Default", "Interactable"]).
• Order matters: the first name is layer index 0, the second is layer index 1, and so on.
• In Blender, the Plume3D addon uses these names for the Tags and Collision Layers checkboxes when a Game Config Path is set to this game.toml.

Each scene node has a tags bitmask and a collision_layers bitmask. Bit 0 = first layer, bit 1 = second, etc. (e.g. collision_layers = 1 means “on layer 0”, collision_layers = 3 means “on layers 0 and 1”).

collision_matrix

collision_matrix defines which pairs of collision layers can interact. It is a list of pairs [layerA, layerB]. Only pairs listed here are considered for collision/raycast between layers. Symmetry is implicit: if [1, 0] is allowed, layer 0 and layer 1 can collide; you do not need to also add [0, 1].

How to configure collision_matrix:

• Each entry must be two integers: [layerA, layerB]. Layer indices are 0-based and refer to the order in collision_layers.
• Example – two layers, “Default” (0) and “Interactable” (1):
  • All pairs collide: collision_matrix = [[0, 0], [0, 1], [1, 0], [1, 1]]
  • Only same-layer: collision_matrix = [[0, 0], [1, 1]]
  • Only Default with Interactable (cross-layer): collision_matrix = [[0, 1]] (or [[1, 0]]; either is enough)
• Example – one layer, “Interactable” (0):
  collision_matrix = [[0, 0]] (that layer collides with itself).
• Invalid: [[0], [1]] (each entry must be a pair [a, b], not a single index).

Example game.toml with Physics:

[Game]
name = "My Game"
version = "0.0.1"

[Window]
width = 800
height = 600
resizable = true

[Physics]
tag_layers = ["Default", "Interactable"]
collision_layers = ["Default", "Interactable"]
collision_matrix = [[0, 0], [0, 1], [1, 1]]

How it’s used

• Raycast: When you raycast with a layer mask, the engine only hits nodes whose collision_layers share at least one layer with the mask. The collision matrix can be used (when implemented) to further filter which layer pairs are valid for collision/query.
• Physics (Jolt): When physics is enabled, the collision matrix from game.toml defines which layer pairs can generate contacts; objects on layers that are not listed in the matrix do not collide with each other.

Blender addon

Set Game Config Path in the Blender addon (on the root collection) to your game.toml. The addon then shows Tags and Collision Layers as named checkboxes matching tag_layers and collision_layers from that file. See the Blender Addon guide.