Making a Map

Making a Map

A map is a course of your own: a glTF scene (made in Blender or any glTF 2.0 editor) whose objects say what they are through custom properties, and a map.toml that names it. A map can be a new track (its own terrain) or a layout on one of the disc's drops (its terrain, with your additions). Maps appear on the game's Maps page and can run on servers.

Start from the template

The game's repository has a template scene, Engine/assets/templates/map/maps/course.gltf: a 60 m wide, 360 m long slope of groomed snow descending along +Z, a metal rail beside the line, the spawn at the top, two checkpoints with a gate marker at the first, the finish across the run-out, and a death volume below everything. Copy it into a package:

slope/
  resource.toml
  map.toml
  maps/course.gltf

resource.toml:

[resource]
name = "slope"
version = "0.1.0"
title = "slope"
description = "A small course: a slope, a rail, two checkpoints and the finish"
api = 1
type = "map"

[add]
"map/course" = "map.toml"

map.toml:

[map]
title = "Template slope"
scene = "maps/course.gltf"
modes = ["race", "freeride"]
intro = "spawn"

The map's id is slope:map/course.

map.toml

Key	Required	Rule
title	yes	1 to 64 characters
scene	yes	the package's .glb or .gltf file
modes	yes	one to five of race, trick, survive, death (survive until you crash), freeride
base	for a layout	the disc drop it sits on: ssx:drop/<name>
midground	no	a new track's distant scenery: a disc track's (ssx:track/alps0101), drawn far off without collision
lighting	no	a lighting preset of the disc: ssx:lighting/<name>
sky	no	a sky id
postfx	no	a post-processing preset of the disc: ssx:postfx/<name>
music	no	a disc song (ssx:music/licensed/<id>) or a package's song or playlist
time_limit_s	no	above 0, at most 3599.999
intro	no	"spawn" (the default): the ride starts at the spawn

The scene

Every node that matters has a custom property ava_type (glTF extras; Blender's "Custom Properties" export as extras). Other ava_* properties set its details. glTF's axes and units apply: +Y up, metres. An empty without ava_type is a group. A mesh without ava_type, an unknown ava_* key, or a key its type does not read is an error that names the node's path (root/child/…) and the key.

ava_type	Is	Keys
terrain (mesh)	snow and rock the rider rides, drawn	ava_surface (a snow surface), ava_material
rail (mesh)	a rail to grind	ava_surface (an object surface), ava_hidden (true: not drawn), ava_material
collision (mesh)	collision that is not drawn	ava_surface (an object surface), ava_group (0, 1, 2 or 11)
prop (mesh, or an empty with ava_object)	a drawn object: its own mesh, or a game object (ava_object, with its collision)	ava_object, ava_ao (0 to 4), ava_material (own meshes only)
spawn (empty)	a start place; its +Z is the heading	ava_slot (0 to 9 without a gap; 0 is the player's and a new track needs it)
checkpoint	a gate, passed in order	ava_order (0 to 49), ava_radius
finish	where a run ends	ava_radius
death	a rider entering it dies; a rewind within 4 s undoes it, otherwise the run ends	ava_radius
trigger	a named volume	ava_name, ava_radius
boundary (mesh)	the in-bounds area, seen from above; outside it the out-of-bounds wind pushes riders back
marker (empty)	a marker drawn at the node	ava_marker (a marker id, e.g. ava:marker/gate)
heli_path (empty)	a point of the helicopter's path	ava_order
camera (a glTF camera)	a named camera	ava_name

• Snow surfaces (terrain): powder, windswept, crusty, wet, groomed, crud, rock, ice.
• Object surfaces (collision, rails): powder, rock, ice, wood, metal, concrete, metal_hollow, and each but powder with _snow (wood_snow …). A collision or rail mesh needs one, on its node, its mesh or its material.
• Materials (ava_material): a material id of the disc or your package; terrain uses ssx:material/terrain_default_mat by default, a rail ssx:material/terrain_rail_red_mat.
• Volumes (checkpoint, finish, death, trigger) are a mesh (its box) or an empty with ava_radius (a sphere).
• A new track needs ground (a terrain or collision mesh) and spawn slot 0. Every mode but freeride needs a finish.

Limits

What	At most
spawns	10
checkpoints	50
volumes	2 048
markers	1 024
cameras	64
collision triangles	1 824 266
coordinates	±131 072 m
a node's extras	4 096 bytes
the scene's vertices and triangles	4 194 304 each
the scene file	256 MiB

Try it

1. Install the package from the launcher's Mods page, or start the game with --mod-dev <folder> while you work on it (Making a Mod).
2. Open Maps on the Project Avalanche menu, pick the map and a mode.

The install's check reads the whole scene and reports what it found:

slope:map/course: a new track — 1 terrain meshes, 0 collision and 1 rail meshes (444 collision triangles), 0 props (0 own meshes), 1 spawns, 2 checkpoints, a finish, 0 triggers, 1 death volumes, no boundary, 1 markers, 0 helicopter points

Not yet

• intro = "heli" (the helicopter drop-in along heli_path nodes) is accepted by the check but the helicopter is not flown yet; servers refuse such a map.
• camera nodes are read but not used yet, and scripts get no event for trigger volumes.
• No map editor or Blender add-on yet: use any glTF editor that keeps custom properties.