The docs.

Make custom parks, objects, skaters and boards for Tony Hawk's Project 8 in Blender, build them into a mod, and play them in the Project 8 Plus native PC port. A mod is a folder with a manifest and the creator's own files; the kit reads your own copy of the game to build it. Nothing from the game is ever part of a mod (CONTRIBUTING.md).

Scope: US disc BLUS30011, version 01.02, and the native port's mods overlay. There is no install path for RPCS3.

Related pages: models.md (geometry and skin formats in full), hd-textures.md (texture formats and the video memory budget), qb-toolchain.md (PAK and QB formats), development.md (setting up the tools, the THP8_* variables).

What a mod can do

Status

Everything in the table above builds with the kit and runs in the native port:

• packaging: several mods built into one combined pack, and modkit.py uninstall restores the unmodified game;
• objects: zone objects replaced and new objects added (with or without a level node), drawn where they are placed;
• textures: zone textures replaced or recolored, skater and create-a-skater parts recolored, meshes such as a cap added to a skater, deck graphics and griptape changed;
• collision and nodes: added objects are solid and can be ridden (a kicker launches the skater, a wall stops him), new game objects and restart points, moved nodes, and grind rails the game builds and grinds (collision-rails.md);
• people and goals: see the status in peds.md and goals.md.

The Blender add-on is a preview: it has not yet been used in Blender itself.

Known limitations:

• skin.griptape has no visible effect on a board whose griptape swap texture is not in the board's texture dictionary (Tony Hawk's "Generic 1"). Use skin.replace_texture instead, for example {"skin": "board_default", "texture": "63c69f4c"}.
• static.replace_mdl and replacing a whole skater with skin.replace_part are covered by the kit's offline tests only.

What you need

• Your own copy of the game: Tony Hawk's Project 8, US disc BLUS30011, version 01.02, as the folder the native port runs from (the folder that contains PS3_GAME). The kit reads it; it never writes to it.
• The native port (Project 8 Plus for PC). Mods go into its mods folder (next to the port's executable, or the folder the PS3_MODS_ROOT environment variable names).
• Python 3.11-3.13, 64-bit, with numpy, pillow and quicktex (pip install numpy pillow quicktex). moderngl is only needed to render previews with the kit's renderer; development.md lists the extras of the other tools.
• Blender 4.x for the 3D work (blender.md, blender-addon.md). Any glTF 2.0 tool works too; the kit only reads .glb / .gltf files.
• This repository, for the tools in tools/modkit and the example mods in examples.

Tell the tools where the game and the mods folder are, once per shell:

set THP8_DATA=<install>\game\PS3_GAME\USRDIR\DATA
set THP8_MODS=<install>\mods

(or pass --game and --mods to every command). THP8_DATA must be the stock game; HD texture packs and other mods live in the mods folder, not in the game folder (packaging.md).

The workflow

1. Export what you want to change from your game files to a glTF file: a zone, a prop, a skater, a board, a clothing part (python tools/modkit/modkit.py export zone z_houses). The exported files are yours to edit and stay on your PC; do not share them. Skip this step for something wholly new (a ramp from scratch).
2. In Blender, import the .glb, change or add meshes, UVs, materials, then export glTF again (blender.md). Axes need no conversion: Blender's exporter writes +Y up, which is the game's up axis.
3. Write a manifest. A mod is a folder with modkit.json and an assets/ folder holding your glTF and PNG files (python tools/modkit/modkit.py new "My mod" scaffolds one). The manifest lists the operations to apply (packaging.md, operations.md).
4. Build with python tools/modkit/modkit.py build <mod folder> --mods <install>\mods. All mods you pass are applied in load order to your game's files and installed as one pack in the mods folder.
5. Start the native port. Its log shows [mods] lines with the files it serves from the pack. After a change of the mod set the game rebuilds its HDD cache once, so the first start is a little slower.

A first build: the examples

The three example mods are made of our own content. Check and build one:

python tools/modkit/modkit.py validate examples/houses_ramp
python tools/modkit/modkit.py build examples/houses_ramp --mods <install>\mods
python tools/modkit/modkit.py status --mods <install>\mods

validate checks the manifest, the operation names, that every asset exists and that nothing in the package looks like game data, without touching the game. The build prints one block per operation, then what it changed (abridged):

game : <install>\game\PS3_GAME\USRDIR\DATA  (BLUS30011 01.02)
pack : <install>\mods\zz_modkit  (base: game)
mods : example.houses_ramp 1.0.0 (p50)
[example.houses_ramp#0 static.add_object]
  snap_to_ground: ground at y=2.393, moved by +0.003 m
  new object modkit_kicker (1a5ec2a9): 1 meshes, 74 triangles, ... + LevelGeometry node
  WARNING: z_houses_vram is now 14,834,432 B (> stock slot 14,786,560 B): every zone link slot grows, 0.19 MiB ...
...
[example.houses_ramp#4 nodes.add_rail]
  z_houses: rail z_houses_modkit_rail_line_0..1 (2 nodes, 3.00 m, terrain MetalPole, node indices 2181..2182)
result: 2 file(s) changed, 6 pak entries changed
  ZONES/5EF17586.CHK       z_houses_vram.pak.ps3               14,852,096 B  base game  by example.houses_ramp
  ZONES/D34E37E4.CHK       z_houses.pak.ps3                     1,898,496 B  base game  by example.houses_ramp
  budget zone_vram_slot: 14,852,096 / 28,119,040 B (... predicted free VRAM 58.61 MiB ...)
INSTALLED <install>\mods\zz_modkit: 2 file(s), 5 op(s), 30.4 s. The port picks it up at its next start ...

The three examples build together in under a minute (19-34 s measured, at low priority on a busy PC). status verifies the installed pack: every file's SHA-1, that the base game files did not change since the build, that no pack sorting after it replaces the same files, and that the mods' folders did not change (exit code 0 = fine, 1 = damaged, 2 = rebuild needed, 3 = not installed, 4 = shadowed).

Use --dry-run to run a whole build without installing anything: the output, warnings and budgets are the same.

The ramp example puts a kicker and a rail in the garage in front of the free-skate start (the Houses zone is where free skate begins); the other two change Tony Hawk's deck graphic and give him a recolored T-shirt and a cap.

Enable, disable, remove

The kit installs one pack, by default <mods>\zz_modkit (the name sorts after hd_textures and every pack named a..y, so the build sees what those packs serve).

The game files are never modified: with the mods folder empty (or the pack gone) the port serves the original files again from its next start, and resets the game's HDD cache once so that nothing of a removed mod lives on in it.

Make a mod and share it

A mod folder holds only your own work and can be shared as a folder or, with modkit.py package, as a zip. Check before you do:

• no game content anywhere: not a file the exporters wrote from your copy, not a texture or model derived from the game (a texture.recolor / skin.recolor manifest is fine, a recolored copy of the picture is not);
• the manifest has the mod's id, version and author, and a license for your own files.

See packaging.md. Whoever installs your mod builds it against their own game copy.

If something goes wrong

The operations are verified offline (every rebuilt file parses back, the examples render correctly in the kit's own renderer) but have not been tested in the running game yet (operations.md); a crash is possible. Please report one with the mod and the port's log.

The Create page of the P8Plus launcher is a 3D editor for Tony Hawk's Project 8 levels and the hub for everything a mod can add: ramps and rails, props, restart points, texture edits, people, goals, stories and cutscenes, and Lua scripts. What you make is a normal modkit mod. The editor reads your own copy of the game, writes modkit.json plus your own assets, and builds the mod with the kit. "Test in game" plays it.

Running it

Open the launcher and go to Create. The first start reads the level from your game files, which takes about 10 s per level. After that the level loads in under a second from a cache in %LOCALAPPDATA%\P8Plus\editor\cache.

Running the editor from source and its test suites: DEVELOPING.md.

Using it

Architecture

launcher (imgui-bundle, hello_imgui)                 thp8-mod/tools
  Create page ── CreateWorkspace(EditorApp) ──────── editor/
                                                      app.py        EditorApp: document, zone, selection, tools, tasks
                                                      workspace.py  toolbar, dock layout, budget bar, shortcuts
                                                      viewport.py   camera, gizmos (ImGuizmo), picking, place/rail tools
                                                      gl.py         moderngl renderer (zone, sky, meshes, collision, lines)
                                                      panels.py     outliner, properties, palette, assets, console,
                                                                    budgets, build & test, scripts
                                                      entities.py   editor objects -> modkit ops (regenerated from params)
                                                      prims.py      parametric pieces: mesh + collision + rails
                                                      schema.py,    SCHEMA / QUERIES of the ops modules: generic
                                                      schema_ui.py    property panels, gizmos and markers
                                                      zonecache.py  level geometry, textures, nodes, collision, rails
                                                      assetlib.py   the game's props / objects, meshes, thumbnails
                                                      texedit.py    texture edits + live preview
                                                      buildtest.py  build (modkit), budgets, launch, share
                                                      livelinkc.py  live link client (hot reload, teleport, events)
                                                      contrib/      content-area panels (story, cutscene, ...)
                                                    modkit/        the build: ops_static, ops_texture, ops_collision,
                                                                   ops_nodes, ops_rails, ops_goals, ops_peds,
                                                                   ops_story, ops_script ... -> one overlay pack

• The document is the mod. modkit.json is the only project file. An editor object is one or more ops sharing x_editor.entity. Its primary op holds the editor's description (kind, params, xf = position / yaw / scale), and the editor regenerates the ops from it whenever something changes. The build strips every x_ key. Generated meshes go to assets/gen/. The contract with the content areas is contract.md.
• Nothing from the game is in a mod. Pieces are generated with procedural textures. Game props are referenced by name (static.add_object game_model) and copied from the player's own files at build time. Texture edits ship parameters or the creator's own layer.
• Caches (level meshes, thumbnails, the pak index) live in the user's local app data, never in the bundle.

Status

Tested in the native port, in Houses:

• A street park built in the editor (a quarter pipe, a kicker, a ledge, a funbox, a drawn rail, a restart and a collect goal): Test in game starts free skate where the camera looks, the pieces are where they were placed, and the goal authored in the Properties panel runs with its text, its timer and its tapes.
• The same park with a Lua script mod and the live link: after an edit the running game reloads the level in about 7 s, without a restart, and the skater is put back.
• Grind rails on copings, ledges, funbox rails and drawn rails are built by the game and can be ground.
• A 60 m park-from-scratch slab is evenly lit and can be skated.

Known limits:

• Light baking is approximate: sky occlusion and sun shadow from the level's collision and the other pieces, written as vertex colors over the level's lightmap. There is no real lightmap bake. Pieces shade each other only within 12 m, and only on vertices with an edge of 1.5 m or less; a large flat surface has coarse cells away from its edges.
• Pieces exist in the full zone only. They are not in the zone's distant _lod stand-in.
• A change to rails, goals or scripts needs a level reload in the live game. Geometry-only changes take the 3-4 s zone reload once the test build has padded the zone's video memory (static.reserve_vram, test builds only).

Script mods change what happens in the game: custom challenges and goals, stories, HUD counters, gameplay tweaks, characters who talk. They are Lua 5.4 scripts that react to game events (a trick landed, a goal won, a level loaded, ...) and drive the game through its own script system (QB): the same scripts, functions and UI the game uses itself.

Script mods run in the native PC port only, with the script-mod host plugin thp8_mod_modapi.dll. Without that plugin, or without any script mod installed, nothing of this runs and the game is unchanged.

• Machine-readable API reference (the editor's autocomplete): scripting_api.json
• Example mods: examples/scripts/
• The modding kit op that packages scripts: script.add (ops_script.py)

Contents: quick start | mod.json | the Lua environment | events | tasks and waiting | calling the game (qb) | API reference | examples | native plugins | how it works | limits

Quick start

1. You need the port's mod-capable exe (the P8Plus build, plugin ABI 1.2 or later) and thp8_mod_modapi.dll in <mods>\plugins\ (<mods> is %PS3_MODS_ROOT%, else the mods folder next to the exe).
2. Make a folder for your mod in <mods>, with a mod.json and a scripts\main.lua:

<mods>\
  plugins\thp8_mod_modapi.dll
  hello\
    mod.json            {"id": "hello", "name": "Hello", "version": "1.0.0", "main": "scripts/main.lua", "api": 1}
    scripts\main.lua

-- scripts/main.lua
log.info("hello from", mod.id)

events.on("level_ready", function()
  hud.message("Hello, skater!", { time = 3000 })
end)

events.on("trick_landed", function(c)
  log.info(string.format("landed %d tricks for %d points", #c.tricks, c.score))
  if c.score > save.get("best", 0) then
    save.set("best", c.score)
    hud.message("New best combo: " .. c.score)
  end
end)

3. Start the game. The game's log shows the host and your mod:

[mod:thp8_mod_modapi] 1 script mod(s) found under ...\mods; Lua 5.4.7
[mod:thp8_mod_modapi] [hello] scripts/main.lua:2: hello from	hello
[mod:thp8_mod_modapi] [hello] loaded: Hello 1.0.0 (...\mods\hello)

Errors in a script are logged with the file and line ([hello] scripts/main.lua:9: attempt to ...) and never stop the game: the failing handler is skipped, the rest of the mod keeps running. With the live link connected, the editor reloads a mod in place (script.reload) and shows these lines in its console.

mod.json

The modding kit writes this folder for you: script.add / script.dir / script.file / script.config ops in a modkit.json produce <mods>\<mod id>\mod.json + scripts\ when the mod is built (the folder is marked "built_by": "thp8-modkit"; the kit never overwrites a hand-made one). A mod can carry both kinds of content: data (levels, objects, textures, through the mods overlay) and scripts.

The Lua environment

• One Lua state per mod. Mods cannot see or break each other's variables. They talk through game events, events.emit is per mod.
• Sandbox. Available: the base library (without dofile / loadfile; load accepts text only), string, table, math, utf8, coroutine, os.time / os.clock / os.date / os.difftime, debug.traceback. Not available: io, os.execute and friends, package, C modules, bytecode. Files: mod.read / mod.json / mod.list inside the mod's own folder, save.* for the mod's save data.
• require("a.b") loads scripts/a/b.lua of the mod (cached), else a built-in library (<plugins>\thp8_mod_modapi_lib\, e.g. require("peds")).
• Game thread. Every handler, task and QB call runs on the game's main thread, between frames or inside the game's own script calls. There is no locking to do. A handler should be short: a script that runs longer than max_ms (default 250 ms) in one go is stopped with an error ("endless loop?").
• Memory. Each mod may use up to 64 MiB of Lua memory (max_mem_mb).
• Errors are caught at every entry from the game into Lua, logged with a traceback, and counted; after 200 errors only every 100th is logged.
• print and log.info / log.warn / log.error write to the game log with the file and line.

Host settings (<mods>\plugins\thp8_mod_modapi.ini): max_ms, max_mem_mb, mods (another folder to load script mods from), always = on (load the host even without script mods, for native plugins that use its services).

Events

local h = events.on("trick_landed", function(c) ... end)   -- subscribe
events.once("level_ready", fn)                               -- next time only
events.off(h)
events.emit("my_mod.step", { n = 2 })                        -- this mod's own events
events.define("big_combo", "trick_landed", function(c) if c.score > 100000 then return c end end)

Named gameplay events (payload fields; "source" = how the host sees it):

Any game script, CFunction or event can be watched by name too:

Names are case-insensitive. The game-side hooks for these are only switched on while some mod listens, so an unused tap costs nothing. Skater events (*_start, bail, ...) are the local skater's only.

Tasks and waiting

A task is a function that can wait without blocking the game (a Lua coroutine resumed by the host every frame):

task(function()
  hud.message("3"); wait(1)
  hud.message("2"); wait(1)
  hud.message("1"); wait(1)
  hud.message("GO!")
  local c = wait_event("trick_landed", function(c) return c.score >= 10000 end, 60)
  if c then hud.message("made it: " .. c.score) else hud.message("time is up") end
end)

A qb.call whose callee waits (a script with waits, a dialog that blocks) suspends the task until the callee ends. Outside a task it returns nil, false, "pending" and the callee keeps running on its own.

Calling the game (qb)

THP8's game logic is mostly QB scripts plus C++ functions those scripts call ("CFunctions") and functions of game objects ("member functions", e.g. Skater:Obj_SetPosition). qb.call runs any of them by name, on the game thread, exactly as a QB script would:

local r, ok = qb.call("GetCurrentLevel")                       -- CFunction with results
log.info(tostring(r.level))                                    -- load_z_houses
qb.call("create_panel_message", { text = qb.wstr("Hi"), time = 2000 })   -- a QB script
qb.call("Obj_SetPosition", { position = qb.vec(-63, 2.4, -66) }, "Skater") -- member function on an object
local _, won = qb.call("GMan_HasWonGoal", { goal = qb.key("my_goal") })  -- condition: ok = its result
qb.call("ChangeNodeFlag", { qb.key("NODEFLAG_Z_HOUSES_CHALK"), 1 })     -- unnamed params

Parameters (Lua -> QB):

Results: qb.call returns results, ok. results holds what the callee returned (a CFunction's results, a script's return x = ...), converted back (checksums as qb.key values that print as their names, vectors as qb.vec, wide strings as UTF-8 strings). ok is the boolean result (CFunctions and member functions; true for scripts).

Trick data: pass qb.global references, not copies. The game's trick scripts trust their params. An AnimData struct without the animation names hangs the game thread inside the game's own trick code for good (seen in game). Pass the game's own data by reference: AnimData = qb.global("ChristianAir_Data") (QB's $ChristianAir_Data), never a Lua copy of it (qb.get_global copies lose array element types and every member whose name the host cannot spell). qb.call / qb.spawn / qb.call_on check the known trick entry points before the call, directly (qb.call("GrabTrick", p, "Skater")) or through MakeSkaterGoto / MakeSkaterGosub ({qb.key("GrabTrick"), params = p}): GrabTrick, fliptrick, InvertTrick, manual, NoseManual, Flatland, ManualFlip. A missing required param (Name, score, AnimData), a wrong type, a qb.global that names no struct, or an AnimData that lacks one of the members every one of the game's own trick tables has for that script raises a Lua error naming it, and nothing is called. A complete copy passes with a one-time warning.

qb.call("MakeSkaterGoto", { qb.key("GrabTrick"), params = {
  Name = qb.wstr("Christian Air"), score = 1250, AnimData = qb.global("ChristianAir_Data"), IsSpecial = true } })

Other ways into the trick scripts (e.g. SpawnSkaterScript, a QB script of your own made with qb.script) are not checked.

Lua functions callable from QB: qb.register(name, fn) defines a QB CFunction whose body is Lua. Use it for callbacks the game calls by name: dialog buttons (pad_choose_script), a ped's activation_script, goal scripts.

qb.register("MyMod_Choice", function(params, ctx)
  log.info("button", params.choice)            -- the call's params
  ctx:call("Obj_PlayAnim", { Anim = qb.key("Idle") })   -- member function on the calling object
  return { picked = params.choice }             -- added to the caller's params (or return true/false)
end)

qb.script(name, steps) defines a real QB script made of calls (steps: "Name" or {"Name", params, object}), which the game runs like its own: as a spawned script, a callback, or a camera's ControlScript on the camera object (camera.look is built on it).

qb.override(name, fn) replaces an existing global script or CFunction of the game with a Lua function (the original comes back when the mod unloads). Globals: qb.get_global / qb.set_global (int, float, name), qb.get_field / qb.set_field (one member of a global struct, e.g. the physics tuning in skater_physics).

API reference

The full list with signatures and examples is scripting_api.json; in short:

mem.* reads and writes guest memory through typed accessors (values are converted from the console's big-endian layout). Writes are refused outside the game's data and heap ranges (code, stacks and device memory are off limits). Prefer qb.* where it can do the job: guest addresses differ between game versions.

Save data (save.*) is a JSON file per mod, <mods>\_modsave\<mod id>\save.json, written atomically within 10 s of a change, on reload and at exit, or at once with save.flush(). The game's own saves are never touched.

Examples

examples/scripts/ has four complete mods; copy a folder into <mods>:

Native plugins (C)

Native plugins (other DLLs in <mods>\plugins) use the host through two services (plugin ABI 1.2 host->service_get), declared in thp8_game.h:

• "thp8.game": on_frame / post (run code on the game thread with a guest context), qb_call_json (sync, game thread), qb_run (any thread, async, completion callback; params as JSON with "#name" / {"$vec": [x,y,z]} etc.), qb_key, qb_global_int / qb_global_float, skater_pos / skater_vel.
• "thp8.modapi": reload(mod) (the live link's hot reload), call(mod, fn, args_json, done) (a mod's mod.exported function), set_log_sink (script output + errors with file and line), count.

How it works

The port's lifter compiles every PPU function of the game into C, with a guard at each function's entry, so the mod-capable exe can wrap any game function at run time (plugin ABI 1.2 hook_add). The host:

• pumps the game thread from the frame step (sub_5C1E18): Lua tasks, the frame event, queued work;
• calls QB by writing a tiny QB script ("stub") into the game's symbol table and starting it with the game's own SpawnScriptNow code (sub_375790): if [object:]Name <params as literals> then modapi_ret __mcid = <id> __ok = 1 <...>. The callee's results land in the stub's params; modapi_ret is a CFunction whose body is the host's trampoline, so the results come back to Lua the moment the callee returns, in the same frame or (if it waits) frames later;
• defines Lua CFunctions as QB symbols of type CFunction whose function descriptor points at a dead game function (sub_42CEBC, the retail-unused QB text compiler) that the host replaces; the descriptor's TOC word carries the Lua function's id;
• taps script starts (CScript::SetScript sub_43DC9C, script calls sub_43DE70), CFunctions (their own entries), and the game's event funnel (sub_3C41DC, every LaunchEvent / BroadcastEvent / exception), each only while a mod listens;
• hooks a few C++ gameplay functions directly: trick text (Display 0x7DA0CC), combo banked / lost (ClearPanel_Landed 0x7D6474 / ClearPanel_Bailed 0x7D743C), gaps (EndGap 0x799A7C), pause (sub_817884);
• reads the local skater (sub_38BEF4 on the skater manager *(0x100E82C4); position +0x70, velocity +0xD0, score object *(*(skater+0x2C4)+0x18)).

Host-made symbols are flagged "file-backed" so the game never frees them; strings and scripts the game must read live in a host-owned guest heap (plugin ABI 1.2 guest_alloc, 0x7C000000..0x7F000000). Addresses are for the US disc BLUS30011 01.02 (PPU-de89165d4428c218f9ade10050ea093f7bde9e8d); the plugin refuses to load on anything else.

Status

Tested in the native port, in free skate in Houses:

Not yet tested in game: the goal_* and ped_* events, career, game_saved / game_loaded.

Limits and known issues

• One game version (above). Guest addresses in mem.* code are version-specific too.
• Returning arrays or vectors from a Lua CFunction (qb.register) is not supported yet (structs, numbers, strings, names and flags are).
• combo / trick_landed come when the game banks the combo, which is a few frames after touchdown (the revert / manual window) or when a manual / grind that continues the combo ends.
• level_ready also fires at the start of every run (career runs, retries) and in the front end; check skater.exists() or your own objects before acting on it. GetCurrentLevel (game.level()) can return no level outside a level.
• Struct copies: a table read from the game and passed back (e.g. qb.get_global of trick data) loses array element types and any member whose name the host cannot spell; pass qb.global(name) instead.
• If the game thread stops running frames for 10 s, the host logs a watchdog warning naming the last QB call a script mod started (a QB loop that never waits stops the whole game). For example, MakeSkaterGoto GrabTrick with an AnimData struct that lacks the animation names hangs the game thread inside the game's own trick code; the trick guards refuse such a call with a Lua error before it reaches the game. Pass the game's own data (qb.global).
• A script that blocks forever (waits for something that never happens) keeps its call slot; at most 256 QB calls can be pending at once.
• Hot reload rebuilds the mod's Lua state; QB scripts it spawned keep running, and a Lua CFunction of a mod that was removed returns false.

A story mod adds a campaign to the game: chapters of quests, characters who talk to you, dialogue trees with choices, in-engine cutscenes, triggers, rewards and its own saved progress. It is written as one YAML file or built in the editor's Story and Cutscene panels; the modding kit compiles it, and a Lua runtime (on modapi) plays it with the game's own dialogue boxes, talk prompts, cinematic cameras and goals.

Status: stories run in the game (native port with the modapi and live-link plugins). The example below plays from start to finish in game, including Play from here from the editor; the format, compiler and runtime are also covered offline by the simulator tests.

The story format

p8story/1. A story is one document. You can write it two ways:

• a YAML or JSON file in the mod, built by the op {"op": "story.file", "source": "assets/story/kicker.yaml"} (like every build input, it lives under assets/);
• editor ops, one per entity: story.story, story.character, story.chapter, story.quest, story.dialogue, story.cutscene, story.trigger. These are what the editor writes. Every op names its story with "story" (default: the mod's only story.story).

tools/story/storyfmt.py converts both ways (ops_from_doc, doc_from_ops), and the compiler accepts either. Check a file on its own with python tools/story/storyfmt.py assets/story/kicker.yaml. It prints every error with its place, e.g. quest warm_up.steps[0]: no goals.* op named 'kick_scor'.

YAML here is the subset in tools/story/miniyaml.py, since the kit runs on the launcher's Python, which has no PyYAML. It has block and flow mappings and lists, quoted and plain scalars, block scalars (|, >) and comments, and follows YAML 1.2 rules: yes is a string, 1e3 is a number. Anchors, aliases and tags are refused with an error, never misread.

Conventions:

• Names (ids) are lower-case a-z0-9_, starting with a letter.
• Positions are world meters in the game's frame (Y up, right-handed), the same as the modding kit and the editor.
• yaw is in degrees about +Y; 0 faces +Z.
• pitch is in degrees, positive looks up.

Top level

story: kicker                       # id
title: "Project 8 Plus: The Kicker"
summary: ...
zone: z_houses                      # where the story's characters live (default zone of spawns, prompts)
start: {level_enter: z_houses}      # when the story begins (below); default: entering `zone`
characters: {rory: {...}}
chapters: [{id: challenge, ...}, ...]
quests: {meet_rory: {...}, ...}
dialogues: {rory_intro: [...], ...}
cutscenes: {cs_arrival: {...}, ...}
triggers: [{when: ..., do: [...]}, ...]

Start (story and quests): auto, manual (only an action starts it), {talk: <character>, prompt: "..."}, {area: {pos: [x, y, z], radius: m}}, {event: <name>} (an emit action), {level_enter: <zone>}, {after: <seconds>}.

Characters

rory:
  name: Rory                        # shown as the dialogue box title (upper-case, the game's style)
  color: [255, 170, 60]             # title color
  ped: kick_rory                    # a person placed with peds.add (object id = the op name) ...
  spawn: {profile: Profile_Greg_Skater, pos: [x, y, z], yaw: 45, anim: PedM_ArmCrosIdle01_xx, zone: z_houses,
          when: <condition>}        # ... or created by the story when the zone loads
  talk: {radius: 4, prompt: "Talk to Rory"}
  idle: [{rory: "The kicker's not going anywhere."}]   # what they say when there is nothing to do

The talk prompt is the game's own (setup_ped_speech: "Rory: (button) to talk." while you stand near them on the ground and are not in a combo).

Chapters

- id: session
  title: "Chapter 2: Kicker Session"   # shown as a hint when the chapter starts
  requires: <condition>                # default: the previous chapter is done
  intro: cs_arrival | rory_intro | [inline dialogue]    # played when the chapter starts
  quests: [warm_up, three_airs]
  complete_when: <condition>           # default: all its quests done
  on_start: [actions]
  on_complete: [actions]
  outro: ...                           # played when it completes
  reward: {...}                        # same as a quest reward

Quests

warm_up:
  title: Warm Up
  description: Show Rory a real score.
  giver: rory                       # default start: talk to the giver
  start: auto                       # see Start
  requires: {quest: meet_rory}      # becomes available when this holds (and its chapter is active)
  steps: [...]                      # run in order
  on_start / on_complete / on_fail: [actions]
  reward: {stat_points: 1, deck: Decks_Birdhouse_Secret, title: REWARD, text: "+1 stat point."}
  repeatable: false
  optional: false                   # true: its chapter completes without it (side quests, gated bonuses)

Only one quest runs at a time, like the game's goals. Progress is saved after every step. A quest interrupted by a level change or by quitting resumes at its current step.

Steps (one key each):

Any step may have text:, which is shown as the objective line at the top of the screen while the step runs.

Objectives (objective: {...}) are for small beats that do not need a full goal:

All take text, time (seconds, optional), retry (default true) and fail_text. Progress shows as Text 2 / 3 0:41.

Dialogues

Write them as a list of lines and constructs:

rory_intro:
  - rory: "Whoa, careful -- that's my kicker you almost ran over."     # <character>: text
  - say: "(narration has no speaker)"
  - choice:                                                           # 1-4 buttons in the dialogue box
      - text: "I can handle it."
        set: cocky                                                    # actions when chosen
        then:
          - rory: "Big words."
      - text: "Show me how it's done?"                                 # without `then`: continue below
  - if: cocky                                                         # branch on a condition
    then: [{rory: "You said you could."}]
    else: [{rory: "Not bad for a beginner."}]
  - do: [{reward: {stat_points: 1}}]
  - label: again
  - goto: again
  - end

The editor stores the same dialogue as a node graph: {start, nodes: [{id, kind: line|choice|branch|action|end, speaker, text, next, choices: [{text, next, if, do}], cases: [{if, next}], do}]}. When a line comes directly before a choice, the choice shows that line's text above its buttons.

In the game, each line is the game's dialogue box (create_dialog_box) with the speaker as the title and a Continue button, the same look as the game's own NPC boxes (goal_dialog_box). The skater is held still (pauseskaters) for the whole conversation.

Cutscenes

cs_arrival:
  letterbox: true                   # the game's fake_letterboxing
  skippable: true                   # X skips (fades out, then the end placement)
  hide_hud: true
  hide_skater: false
  motion: smooth                    # camera easing over a shot: smooth | linear | ease_in | ease_out
  fade_in: 0.5                      # start from black
  fade_out: 0.5
  duration: 7.0                     # default: the last key / event
  camera:                           # keys; `cut: true` starts a new shot
    - {t: 0.0, pos: [-66.0, 4.4, -69.47], look_at: [-61.05, 2.7, -64.52], fov: 70}
    - {t: 4.0, pos: [-63.9, 3.9, -66.4], yaw: -71.5, pitch: -2, roll: 0, fov: 60}
  actors:                           # placed before the first frame
    - {character: rory, pos: [-61.05, 2.39, -67.35], yaw: -71.5, anim: PedM_ArmCrosIdle01_xx, hide_after: false}
  events:
    - {t: 0.0, fade_in: 0.6}
    - {t: 0.5, text: "Houses. Saturday afternoon."}                     # caption, the game's subtitle style
    - {t: 4.2, line: {speaker: rory, text: "Let's see what you've got.", time: 3}}   # "(Rory) ..."
    - {t: 5.0, actor: {character: rory, anim: PedM_Cheer01_xx, look_at: [x, y, z], hide: false}}
    - {t: 5.2, walk: {character: rory, to: [x, y, z], speed: walk, then: PedM_Clap01_xx}}   # or to: <node name>
    - {t: 5.5, sound: General_Goal_Success_Sound_sfx}
    - {t: 6.0, music: <track>}
    - {t: 6.0, skater: {pos: [x, y, z], yaw: 45, hide: false}}
    - {t: 6.2, do: [actions]}
    - {t: 6.3, wait_input: "Press X"}                                   # holds the timeline until X
    - {t: 6.4, fade_out: 0.6}
  end: {pos: [-63.17, 2.39, -66.64], yaw: 45}                          # or {node: <restart node>}

Each shot plays as one of the game's cinematic cameras: PlayIGCCam with the helper control script p8story_cam_control, which runs CCam_SplineMorph over the keys. These are the keyframes the stock goal-intro cameras use. Each key becomes {LockTo = world, Pos, Quat, FOV, time}:

• Quat holds x, y, z of the orientation quaternion, with w ≥ 0 implied. The camera's forward is R(q)·(0, 0, 1).
• yaw, pitch and roll are converted to it. The convention was checked against the stock E3 fly-in camera of chapter_info.qb.
• In the editor, the keys are {t, view: {pos, yaw, pitch, roll, fov}, cut}.

Actors are the peds library's: walk (or to: on an actor event) is peds.walk_to, the game's scripted mover (Obj_MoveToPos / Obj_MovetoNode with a walk cycle; the agents' own navigation does not move script-made people in free skate), speed walk | walk_slow | walk_fast | run | run_fast, then the then animation (default the character's idle). A character that walked gets its talk prompt where it now stands.

Triggers

- when: chapter_start        # talk | area | goal_won | goal_failed | quest_done | quest_started | chapter_start |
  chapter: session           #   chapter_done | flag | level_enter | event | combo
  once: true                 # default
  if: <condition>
  do: [{hint: {text: "Rory's challenges are on your compass.", time: 4}}]

Parameters by when:

Conditions

These are written as a string or a mapping:

Actions

Every action is a mapping with one verb. It may have if: <condition>.

Rewards:

• stat_points uses the game's AwardStatPoint.
• goal_points adds goal points (CareerFunc AddGoalPoints, as secret spots and gaps do).
• deck / decks mark decks as bought in the skate shop, the way the shop does (shop_decks_bought). The editor's story.decks query lists the ids.
• nodeflags opens areas.
• unlock_goal unlocks a quests goal.
• flag sets a story flag.
• With text, the reward shows a dialogue box (title, default "REWARD") and the game's goal-success sound.

Areas (top level areas:): the career's node-flag unlocks, kept by the story. An area has the node flags of its locked and unlocked looks and the condition that opens it:

areas:
  main_street:
    title: Main Street
    locked: {NODEFLAG_Z_HOUSES_UNLOCKSHOPS_PRE: 1, NODEFLAG_Z_HOUSES_UNLOCKSHOPS_POST: 0}     # the gate shut
    unlocked: {NODEFLAG_Z_HOUSES_UNLOCKSHOPS_PRE: 0, NODEFLAG_Z_HOUSES_UNLOCKSHOPS_POST: 1}   # the gate open
    unlock_when: {all: ["quest:warm_up", {goal_points: 25}]}
    message: {title: "MAIN STREET", text: "The gate to Main Street is open."}               # when it opens in play

A level load resets node flags to the game mode's (free skate: everything open), so the runtime applies an area's flags whenever its zone loads and again when the condition turns true; the open state is saved (areas). The stock area flags of each zone are the *_PRE / *_POST pairs of game_progress_set_initial_story_mode_nodeflags (chapter_info.qb); in Houses NODEFLAG_Z_HOUSES_UNLOCKSHOPS_PRE is the Z_Houses_G_SUBURBS_GATE_LOCKED gate and _POST the open Z_Houses_G_SUBURBS_GATE (plus its grind rails), UNLOCKCRETEPARK_* the way to the skate park.

Time of day: THP8 has no clock, so there is no time trigger. Each level has one lighting set (its TOD manager), and mood changes the look for a scene.

The runtime

tools/story/lua/story/*.lua is a Lua library on modapi. The build copies it into the mod's pack, under scripts/story/, and makes scripts/story/boot.lua the mod's mod.json main (modapi needs a main; when the mod already has one, from script.add name=main, the boot goes to autoload instead). When the mod loads, boot.lua:

• loads every compiled story listed in story/index.json;
• loads the mod's optional Lua hooks (scripts/story_hooks.lua, a module that returns {name = function(story, ...)}; ship it with {"op": "script.dir", "source": "assets/scripts"});
• starts the runtime;
• runs the mod's own scripts/main.lua if it ships one through script.dir (the boot took the main slot).

Things the game does that the runtime allows for (all seen in game):

• Zones come from game.zone(). The game itself reports a level only as its load script's checksum (load_z_houses, nameless in the retail build); modapi's game.zone() turns that into "z_houses", which is what stories name. The front end's menus are a level too: a story with a zone plays only while that zone is loaded, and Play from here answers waiting: <zone> elsewhere.
• Talk prompts are the peds library's (peds.talk, one implementation for every mod). The stock trigger (setup_ped_speech: the ped's AnyObjectInRadius event) never fired for people made by a zone setup script, so the prompt is checked in Lua: within the character's talk.radius, on the ground and not in a trick, the stock-look speech box "Rory: (button) to talk." appears and Circle or Triangle talks. The story passes the character's position (a spawn position or its peds.add op's pos, copied in by the compiler), or lets the prompt follow the person once it walked.
• People appear a few frames after they are created. CreatePedAtPos (zone setup script or Lua) builds the ped later; member calls made before that are lost. The runtime waits for world.exists(id) before animating a character or arming its talk prompt (the keeper retries every frame).
• Back-to-back goals. A goal's end-of-run reset can move the skater after the next goal's restart, so the runtime leaves 1.2 s between a goal's end and the next p8q_goal_start.
• Never raise inside a wait_until condition. modapi's scheduler evaluates conditions outside the waiting task; an error there kills the task without unwinding its pcalls (in game this left the UI lock taken after a reset). H.wait_until catches errors in the condition and raises them again inside the task; the simulator evaluates conditions the same way (tests/reset_mid_box.lua fails on the old code).
• Cutscene end placement after unfreeze. goal_move_skater on the frozen, hidden skater after a goal brought the skater back without its body; the runtime places the skater after unhiding and unfreezing it, and hides skater_board together with the skater (the stock cutscene player does the same).
• No package, io or os in a mod. modapi's sandbox leaves them out; test_storyfmt.py checks the runtime never uses them.

The game side is the stock scripts plus p8story.qb. The build installs it into the main script pak through the kit's shared qbinject. It holds the dialogue-button callback, the talk activation, the camera control script, the skip watcher and the deck unlock. Those scripts hand their results to Lua through globals (p8story_dialog_result, p8story_talk_serial / _who, p8story_skip), and the runtime polls them, so no QB script has to call into Lua. Goals report through quests' globals (p8q_result_serial, p8q_last_goal, p8q_last_result).

Saving: the story state is stored with modapi's per-mod save (<mods>\_modsave\<mod id>\save.json, key story.<id>). The game's own save is never touched. It holds:

• chapter states, and quest states with their current step;
• flags, counters and dialogue choices;
• fired triggers, seen dialogues and cutscenes, and won goals.

The state is written after every step and flushed at quest and chapter boundaries.

Mod scripts can use the runtime:

local story = require("story.runtime")
story.hook("kicker_finished", function(s) ... end)       -- lua: actions / steps / conditions
local s = story.get("kicker")
s:flag("cocky"); s:set_flag("x", true); s:counter("laps"); s:quest_state("warm_up"); s:start_quest("bonus")
s:on("quest_done", function(s, id) ... end)              -- story_start, chapter_start, chapter_done,
                                                         -- quest_started, quest_done, goal_won, goal_failed, story_done

Livelink exports (modapi's mod.export, called by livelink's mod.call):

• story.list
• story.state(id)
• story.reset(id)
• story.play(id, kind, name): jump to a chapter or quest, or play a dialogue or cutscene now
• story.set_flag(id, flag, on)
• story.ui(): the dialogue box on screen ({title, text, buttons}) or false

While a story plays, it emits livelink events so the editor can follow it:

• story.node {story, kind, id, node}: a story, chapter, quest, goal, dialogue node, cutscene or trigger starts;
• story.box {title, text, buttons}: a dialogue box opened (the editor shows "waiting on Rory ...").

Authoring in the editor

There are two panels in the editor's Create workspace, both in tools/editor/contrib. For the plain fields of every story op, the generic Properties window comes from ops_story.SCHEMA; it has gizmos for character spawns, trigger areas, cutscene actors and camera keys.

• Story (story.py):
  • Flow: start, chapters and quests as a node graph at real text size (pan with the mouse). Each node has a colored header and two lines of plain summary ("Talk to Rory", "2 steps: goal, dialogue"). Drag a chapter's quests pin onto a quest to move the quest into that chapter.
  • Dialogue: the conversation tree: lines, choices (one pin per choice, labeled with its text), branches (one pin per case plus "otherwise"), actions and ends. Drag pins to link, press Delete to remove links or nodes, use Add node or right-click to add.
  • Problems: the compiler's errors and warnings as sentences ("Quest “Warm Up”, step 1: there is no goal named “kick_scor” in this mod."). Click one to jump to it.
  • Inspector: typed rows in the editor's property grid:
    • quest start: a "Starts" dropdown (automatically, talk to someone + prompt, enter an area, a story event, only by an action);
    • "After quests" chips;
    • one row per step: kind + goal / dialogue / cutscene / character / seconds, with up / down / delete;
    • reward: stat points, deck, message;
    • action rows;
    • trigger "When" + its fields;
    • character person, talk distance, idle chatter;
    • dialogue speaker, text and choices. Anything more complex is still editable: each group has a Show as text switch with the YAML snippet (the kit's own subset, tools/story/miniyaml.py), checked as you type.
  • Add: one menu for chapters, quests, characters, dialogues, cutscenes and triggers.
  • Play from here: builds the mod. With the game running (livelink) it reloads the mods and jumps the story to the selected chapter, quest, dialogue or cutscene; otherwise it starts the game first. While it works, the button shows the current step with a Cancel.
  • The node the game is playing is outlined.
  • A mod written as a YAML file is offered a one-click conversion to editor ops (the file stays as a backup).
• Cutscene (story_cutscene.py):
  • a timeline with lanes for camera keys, events and actors, a ruler to scrub, and drag to retime; event names and friendly animation names are shown, with details on hover;
  • Add: a camera key from the viewport camera at the playhead, any event, or an actor;
  • Snap to view and Look through move a key to the viewport camera and back;
  • the playhead drives the viewport camera (a preview of the game's spline);
  • Preview in game sends the same camera to the running game over livelink (cam.free + cam.set);
  • the viewport draws the camera path, a frustum per key, and the actor marks.

Screenshots of both panels are made with tools/story/tests/editor_shot.py.

The example: "The Kicker"

examples/story_kicker is a three-chapter story in Houses, around a kicker ramp that the mod builds in front of the free-skate start:

Career-style gates: Warm Up pays 25 goal points, and Main Street (the stock gate out of the Houses garage street) stays shut until Warm Up is done and you have 25 goal points (the main_street area).

Ops:

• static.add_object + collision.add_mesh for the ramp;
• peds.add for Rory: a fixed look, {base: RPed_M_SkaterTeens_NoBoard01, parts: {torso, head, legs}} (every slot chosen, so the same each load; a profile without a skateboard -- a ped with one stands on its board, a separate object, and does not walk);
• goals.add_score, goals.add_trick and goals.add_collect, all locked, started by the story;
• story.file for assets/story/kicker.yaml;
• script.dir for assets/scripts/story_hooks.lua, the Lua hook.

In the native port, with modapi and the live link, the whole example plays through tools/story/tests/ingame_livelink.py and every check passes:

• the story loads, and the intro cutscene flies the camera in over the kicker to Rory;
• the Main Street gate is shut at the start (node flags) and opens after Warm Up's +25 goal points;
• the prompt "Rory: (button) to talk." shows next to him; his dialogue box has the stock NPC look and the choice "I can handle it." / "Show me how it's done?";
• the story starts each goal (Warm Up with its timer and score, Three Grabs, High Flyer) and moves on when it is won;
• Play from here (story.play quest three_airs) jumps straight to Three Grabs;
• in the second cutscene Rory walks up to you (peds.walk_to to a waypoint the build adds), claps, then cheers;
• the payoff dialogue and the reward message follow; back in free skate Rory cheers and his idle prompt returns;
• story.walk outside a cutscene reaches a position and a level node;
• the Top-150 pro line stays locked at rank 200, and Rory looks the same in every run (all three parts of his profile are chosen).

The goals were won through the goal manager's debug win (GMan_DebugBeatCheckpoint), not by skating them; the win travels the normal path (quests' p8q_* globals -> the story -> next step). In free skate the career's AddGoalPoints changes nothing, so the gate counts the points the story itself awarded. Progress is in <mods>\_modsave\example.story_kicker\save.json (story.kicker: chapters, quests, the cocky flag, the choice, won goals, the story's goal-point tally, the opened area).

Play from here also works from the editor. With the game running on the editor's test mods root and the live link connected, the Story panel's Play from here runs Build & Test's live path (build, reload, mod.call story.play); the editor shows "In the game: goal kick_airs" and "Playing in the game" while the game runs the Three Grabs goal. tools/story/tests/editor_play.py --attach drives this.

Testing in game

tools/story/tests/ingame_livelink.py plays a story mod in the running game the way the editor does, through the live link: mod.call to story.reset / story.play / story.state / story.ui, skater.set to walk up to a character, the harness pad file for the buttons, qb.run GMan_DebugBeatCheckpoint to win the goal the story started, and screenshot for proof. The mods root needs thp8_mod_modapi.dll and thp8_mod_livelink.dll in plugins\, and the game runs with PS3_LIVELINK=1.

python tools/story/tests/ingame_livelink.py --mods <mods root> --shots <folder> --press tools/harness/press.sh

It prints one PASS / FAIL line per check (story loaded, intro cutscene, talk + dialogue, goals started by the story and won, Play from here, the finish and the save) and exits 1 when a check failed.

Testing offline

• python tools/story/tests/test_storyfmt.py, all offline:
  • the quaternion convention, against the stock camera;
  • compiler errors;
  • dialogue sugar;
  • the YAML → editor ops → story round trip;
  • two simulator playthroughs.
• tools/story/sim:
  • storysim is a plain Lua 5.4 host built from modapi's vendored Lua by sim/build.sh.
  • sim.lua fakes modapi and the game's scripts and plays a scenario against a built pack. The scenario can walk somewhere, talk to someone, end a goal, land tricks, skip, restart, or call exports.
  • tests/kicker_full.lua plays the whole example: a goal failure and retry, the rewards, and a restart that keeps the progress. tests/features.lua covers objectives, timeouts, reach, talk, if-steps, counters, events, triggers, an editor-op story, and Play from here.
• python tools/story/storybuild.py <mod> --out <dir> builds a story mod's pack files without the game, which is what the simulator loads.

How THP8 does its own story

Every script name below was read in the decompiled scripts of disc BLUS30011 01.02 (tools/qbc/qbc.py dump --pak all); file names are the dump's <name>_<checksum>.q labels.

1. The career is an atom graph (chapter_info_3ebf39b4.q)

chapter_info_data_internal is one array of atoms. Each atom has a Name, a Type, its parameters and a depends_on list; when every dependency holds, the atom fires once. There are no explicit chapter boundaries: the "chapters" are just groups of goal atoms that unlock together.

Atoms are evaluated by the engine (CareerFunc func = UpdateAtoms forces a pass, e.g. after SetGlobalFlag). Typical scr atoms: game_progress_unlock_pro_movie (22), game_progress_clear_pager_message (18), game_progress_save_prompt (15), unlock_skater_and_movie, game_progress_process_goal_lock (lock = 1 goals = [...] hides finished goals), chalk_challenge_unlockscript, funpark_unlockscript.

Area unlocks are node flags: changenodeflag NODEFLAG_Z_HOUSES_UNLOCKSHOPS_PRE 0 / ..._POST 1 swaps the barrier objects of a zone (game_progress_set_initial_story_mode_nodeflags lists all ~150 story flags and their start values). Example chain from the start of the career: m_chalk_intro -> m_chalk_grindhouses -> (lock the intro, chalk_challenge_unlockscript) -> m_photo_houses01 + m_story_dadhouses + m_chalk_grindhouses -> m_unlock_cretepark + a Filmer pager message -> m_film_filmerintro + m_pro_mullen -> m_unlock_houses ... Ranks drive the sponsor chain: Sponsor_<brand>_Message atoms at ranks 160, 150, 140, 120, 110, 100, 80, 60, 50, 40 set CAS_<BRAND>_UNLOCKED flags and send Jason Lee pager messages with the sponsor's Bink clips.

2. Goal presentation (the intro card of every goal)

story_mode_goal_info (goal_info_f2233bb4.q) holds per goal: intro_presentation = { Template, Camera } (or checkpoints = { checkpointN = { presentation = {...} } }), view_goals_title, view_goals_presentation (the description), view_goals_text_am/_pro/_sick (tier texts), start_zone, trigger_Pos, has_intro_cutscene. PlayGoalPresentation goal_id = X (goal_presentation_31c082bd.q) freezes the skater, hides the HUD, plays a camera (PlayIGCCam { <Camera> Name = goal_presentation_igc update_when_paused play_hold = 1 }), optionally a Bink loop behind it (goal_presentation_templates: Filmer, photo, classic have movies), and builds the card: sprite pause_classic_goaltextblotch tinted [20 0 30 125], title in font text_a1 scale 0.65 rgba [100 90 80 255], the info panel (goal_classic_mode_view_info_panel), helper text \m0 ACCEPT / \m1 QUIT, then pauses and blocks on event goal_presentation_finished (goal_presentation_ok / goal_presentation_quit).

3. Cameras: IGC cams and keyframes

• PlayIGCCam { Name, ControlScript, params, play_hold, allow_pause, ExitScript, viewport } (CFunction) creates a cinematic camera object (components CinematicCamera, Locator, Camera) and runs igc_runcamerascript (52f6cdf2.q): with ControlScript it runs that script on the camera, otherwise it does CinematicCamera_DoMorph <params> (a static shot from LockTo/Pos/Quat/FOV), then holds with play_hold. WaitMovie Name = X waits for it, KillSkaterCamAnim Name = X ends it.
• Camera keyframes inside a control script: CCam_DoMorph { LockTo = world Pos = (x,y,z) Quat = (qx,qy,qz) FOV = 72 time = s motion = smooth }, CCam_SplineMorph { motion = smooth keyframes = [ {LockTo Pos Quat FOV time} ... ] }, CCam_WaitMorph, CCam_Yaw deg time = s Block, CCam_Orbit. Quat stores x, y, z of a unit quaternion (w >= 0 is implied). Positions are world meters. Examples: m_film_school_intro_cam (5-key spline), chapter_info_e3_intro_flyin_cam.
• IGC_Camera_MoveToPlayer time = s morphs back to the gameplay camera (skatercam0).
• Stock generic control script: goal_instruction_cam_control params = { camera_points = [ { Pos Quat FOV time motion text } ] } morphs through the points showing text (font text_a1) under each, with a 1 s hold per point.

4. Cutscenes

Pre-rendered-in-engine cutscenes (Cutscene_7b9ec42b.q, 408 CUTSCENES paks): PlayCutscene Name = "c_..." ExitScript = X / GoalPlayCutscene Name = "c_story_skateshop_2". CutsceneSetup hides peds and the skater, pauses objects and spawned scripts, loads the cutscene data (Cut_GEL_*), sets render and game lock to 2 (30 fps), swaps the sound buss to Generic_IGC_BussSet and pauses the user music; CutsceneCleanup / PostCutscene undo all of it, optionally RestartNode to reset the skater. Subtitles: cutscene_subtitles_d59c70dc.q; fades: CutsceneFadeIn/Out time = s.

In-game cinematics (IGC scenes): igc_player_run (igc_player_7698ded1.q) is a data-driven scene player: scene_setup / Template (actors, default_direction, default_behavior, camera_cycle), shot_params = [ { Camera, speaker, frames | waitfor | VO, actor_positions = [{ ActorName, Pos, Quat | node }], actor_directions, actor_behaviors, shot_script, pre/post_shot_script, transition = { in out } } ], gameside_callbacks = { setup, Cleanup, play_text, stop_text, play_camera, stop_camera }, skippable shots, VO streams named <scene>_<shot>_<actor suffix>. PlayIGCScene (b554d8a2.q) wraps it with generic setup/cleanup (letterbox, freeze skater, IGC sound buss) but its play_text callback igc_utils_create_text does not exist in the retail scripts and nothing calls PlayIGCScene or Ped_Utils_SetupIGCSpeech (talk-radius trigger): the system is a leftover from the previous games, intact enough to drive with our own text callback.

Helpers in b554d8a2.q: freeze_skater_for_cinematic / unfreeze_skater_after_cinematic, fadetoblack On|off time alpha (sprite black at z 9000), igc_fadeout / igc_fadein, igc_ped_walk_in, igc_skater_orient, IGC_ped_point / _Wave / _Clap / ... gesture anims, fake_letterboxing [remove], hide_all_hud_items / show_all_hud_items, kill_start_key_binding / restore_start_key_binding.

5. Text boxes

All in 9758d39f.q unless noted.

• create_dialog_box { title text buttons = [ { text pad_choose_script pad_choose_params } ] no_helper_text } -> create_snazzy_dialog_box: centered box (pos (320, 230), z 40), title font text_a1 scale 0.7 [90 90 70 255], text text_a1 0.6 [90 70 50 255] in a 530-wide block, background [8 15 24 170], buttons in a VMenu (create_dialog_button: focus/unfocus colors, pad_choose -> button_choose_script destroys the box, then runs the button's script with its params). dialog_box_exit / destroy_dialog_box remove it and restore input. Several buttons = a multiple-choice prompt for free.
• goal_dialog_box { title text } (ff82ffd6.q) is the stock NPC-dialogue look: pauseskaters, create_dialog_box with title = the speaker ("MASCOT") and one \m0 Continue button, then Block Type = event_dialog_ok.
• create_speech_box { text Pos=(320,350) pad_choose_script pad_option_script pad_back_script no_pad_choose no_pad_start anchor_id z_priority style }: the small bottom box (dialog_frame / dialog_middle / dialog_frame_b sprites, TextBlockElement 540 wide); speech_box_exit fires speech_box_destroyed.
• The talk prompt: setup_ped_speech { ped_id accept_text activation_script activation_script_params inner_radius outer_radius dont_deactivate_goals hide_in_goals text cam_anim } (aee40f82.q), run on the ped (RunScriptOnObject id = <ped> <script>): an AnyObjectInRadius handler shows "<display_name>: \me to talk." in a speech box at (320, 400) while the skater is on the ground and not comboing; the button (pad_option) runs activation_script on the skater. Example: m_unlock_houses_intro_SetUpPedSpeechOnMascot -> m_unlock_houses_intro_PedSpeechInstructions -> goal_dialog_box. Goal givers use the same pattern through goal_trigger_far/near + goal_trigger_dialog_create (goal_utilities_6ef8471d.q: \m5 Talk, radius globals goal_utilities_trigger_radius_inner/outer).
• Text lives in localized string globals $str_<script file>_<n> (d1644c97.q for English), e.g. str_m_unlock_houses_intro_scripts_3 = w"Try to Ollie (\b3) over my RC car... if you can!". Button glyphs are escapes (\b3, \m0, \m5, \me).

6. Rewards, rank, time of day

• CFunctions (work/gfx/cfuncs.json): AwardStatPoint N (the cheat menu gives 100), GetNumStatPointsAvailable, GMan_UnlockGoal, UnlockSkater, SetGlobalFlag / UnSetGlobalFlag / GetGlobalFlag, GetYourRank / SetYourRank, GetSkaterRankings, GoalManager_GetGoalRewardPoints, GMan_SaveGoalStates / GMan_LoadGoalStates, SaveToMemoryCard, GetStatValue.
• goal_rewards (goal_rewards_398b67b8.q): goal points per goal type (story 20, film 20, comp 20, photo 10, chalk 10, classic 30, ...) feed the Top-200 rank.
• Time of day is not dynamic: each level has one TOD manager (*_tod_manager, lighting + screen effects) plus TOD_Morning/Afternoon/Evening On/Off_NN node flags created by tod_manager_nodeflags_setup. Script can blend the look at run time with TOD_Proxim_Update_LightFX fxParam = <tod struct> time = s (the pause menu does this) and restore it with TOD_Proxim_Reapply_LightFX. A story can therefore set a mood per scene, but there is no clock to trigger on.

7. Subtitles and movies

• Subtitles are timed arrays <cutscene>_Subtitles = [ { text = w"(Tony) ..." time = 5.3 duration = 2.6 } ] (cutscene_subtitles_d59c70dc.q, movie ones in movie_subtitles_8f8aa591.q); the speaker is written into the text as (Name). One line is drawn by cutscene_subtitle_create { text duration }: create_panel_block id cutscene_subtitle at (320, 430), font text_a1 scale 0.6, rgba [110 100 90 255], 800 wide, z 115; it does nothing when the global flag NO_DISPLAY_CUTSCENE_SUBTITLES is set (the options menu). cutscene_subtitle_cleanup removes it. This is the look our cutscene text uses.
• Bink: PlayMovie { movie = "name" TextureSlot TexturePri start_frame loop_start loop_end viewport } / KillMovie TextureSlot = n / IsMoviePlaying; full-screen in-game movies go through ingame_play_movie { movie | movies = [...] level }, which tears the level down and reloads it (Change_Level ... from_movie), so a story uses movies on surfaces / goal cards, not full-screen mid-level.

Still to document

Rank computation details, deck/CAS unlocks, the save layout.

Custom goals for the free-skate world, plus how THP8's own goal system works underneath them. The first part is the reference for the goal operations; the second part is the reverse-engineering notes they are built on.

Status: see In the game at the end for what has been run in the native port.

Custom goals

A goal is one operation in a mod's modkit.json (packaging.md), at build phase 60 (after peds):

{"op": "goals.add_score", "name": "myname_garage_score", "title": "Garage Session", "text": "Score 5,000 points!",
 "target": 5000, "time": 60,
 "start": {"trigger": "marker", "pos": [-58.2, 2.6, -65.9], "yaw": 45, "prompt": "Garage Session"}}

Parameters every goal takes:

Pickup / gate models are ones the game keeps loaded in every level, so a mod never ships a model for them: tape (secret tape), classic (classic-mode icon), letter_s letter_k letter_a letter_t letter_e, combo_c combo_o combo_m combo_b, flag_red flag_green flag_blue flag_yellow, stoken, and the marker models.

Trick presets are the game's own trick lists: basic_flip any_flip double_flip triple_flip basic_grab any_grab basic_grind doubletap_grind any_grind slide basic_lip any_lip any_stall stall_or_lip hold_tricks basic_manual revert pivot wallie wallride; any other string is one trick's name as the game shows it (Kickflip).

What the build makes

All the goal operations of a build together make:

1. scripts\mods\p8q_goals.qb in pak/qb.pak (the main script pak, PAK/F56B119F.CHK + F87B73EE.CHK), through tools/modkit/qbinject.py: the runtime library (tools/modkit/goals/runtime.q) plus, per goal, its configuration ($p8q_goal_cfg.<id>), its goal_info ($p8q_goal_infos.<id>) and the callbacks the engine calls by name (<id>_chk1_enter, <id>_chk1_scr_landedTargetScore, <id>_post_activate, ...).
2. The free-skate goal list goal_infos_hsfreeskate (pak/goal_infos/goal_infos_hsfreeskate.pak = PAK/ED31D903.CHK) with the goal infos of every goal that is not locked appended. When free skate (or High Score) starts, the engine adds them like its own goal, initializes them (the start marker or giver appears) and runs them.

Nothing from the game is in a mod: both files are rebuilt from the player's own copy. The build checks that no generated symbol is already defined by the game (or by another mod's script file), that no goal id is a game goal, and records qb_pak.added (bytes added to the main script pak) and goals.count in the build report.

Starting goals from scripts, Lua and stories

The runtime's entry points are ordinary QB scripts, so the modapi Lua bridge (qb.call) and the story ops use the same calls:

Results, when a goal ends:

and the events p8q_goal_won, p8q_goal_failed, p8q_goal_quit (data = {goal = <id>}).

Testing

goals.debug adds a command channel for the test harness: a script started with the first start marker polls the integer globals p8q_dbg_cmd / p8q_dbg_arg, which tools/modkit/goals/qbglobals.py writes through the port's PS3_DEBUG console (mem / poke32 on the engine's script-global hash table). Commands: 1 start goal #arg (index into p8q_goal_ids), 2 teleport to point #arg of the active goal (pickup / gate / gap region), 3 quit, 4 beat the checkpoint (GMan_DebugBeatCheckpoint), 5 unlock goal #arg, 6 set the skater's speed, 7 run-up #arg of a gap goal (placed before from, facing to, with a speed), 8 move to the goal's restart, 9 lock goal #arg, 10 goal #arg state into p8q_dbg_out (0 missing, 1 added, 2 initialized, 3 active). Each command bumps p8q_dbg_ack. Never ship a build with goals.debug.

python tools/modkit/goals/qbglobals.py --dbg <run dir>/dbg.txt cmd 1 0          # start goal 0
python tools/modkit/goals/qbglobals.py --dbg <run dir>/dbg.txt get p8q_last_result p8q_result_serial

How THP8's goal system works

Everything below was read from the game's own scripts (decompiled with tools/qbc) and its executable.

The goal manager ("GMan")

The engine's goal manager is C++ (script functions GMan_*, about 130 of them, plus GoalPakManager_* and GoalManager_*). Goals are data: a goal_info structure per goal, and script callbacks found by name.

Where goals come from (per game mode)

init_goal_manager game_mode=<mode> (goal_utilities.qb) loads a small pak, calls GMan_AddGoals game_mode=<mode> and unloads the pak again: the goal manager copies the goal infos into its own objects. GMan_AddGoals (code 0x91A6B8 -> 0x832708) picks the global array(s) by mode:

Then GMan_LoadGoalStates, GMan_SyncGoalsWithCareer and (once the skater exists) GMan_InitializeAllGoals. A single goal can also be added at run time from any script: GMan_AddGoal goal_info=(<struct>) (the developers' test level z_testlevel_mb does this), then GMan_InitializeGoal, wait for GMan_GoalIsInitialized, then GMan_ActivateGoal; and the reverse: GMan_DeactivateGoal, GMan_UnInitializeGoal, GMan_RemoveGoal.

Goal types (goal_types / goal_rewards, goal_rewards.qb): Bail chalk classic comp demo elimiskate film getthere hsfreeskate nail net photo pro_challenge race story training turf unlock. goal_rewards.<type> gives the menu name, goal_points (career progression points: 0-30) and the leaderboard columns. chalk, turf and training goals are "permanent" (they stay in the world after being won); won goals of other types are uninitialized.

Goal life cycle

added -> initialized (the intro: trigger ped / marker created; paked goals load <goal>_intro) -> activated (paked goals load their mission pak; <goal>_post_load or, for pakless goals, <goal>_post_activate; the first checkpoint is entered) -> checkpoints pass / fail -> won / lost (goal_win / goal_lose: messages, rewards, leaderboard) -> deactivated (<goal>_post_unload / <goal>_post_deactivate) -> back to initialized (or uninitialized when won and not permanent).

goal_info

{
    Name = "m_photo_shops02"          // string: the goal id is its checksum
    goal_type = photo                 // one of $goal_types
    data = { ... }                    // free per-goal data: GMan_GetData / GMan_SetData
    pak_info = { main = { size = 1 } }// mission pak Missions/<name>/<name>.pak (+ intro); absent = a "pakless" goal
    ped_info = [ { Name profile|Model Pos Quat exists_in = intro|main|both activates_goal prompt_text ... } ]
    no_success_messages / no_fail_messages / no_retry / classic_goal / ...
    checkpoints = [
        { Name = "checkpoint1"  next_checkpoint = <name>  enter_restart_node = <node> | enter_restart_pos = {Pos Quat}
          retry_node  dont_reset_score
          tools = [ { Name = "timer1" Type = timer start_time = 120 end_time = 0 beep_time = 10 expires_checkpoint ... }
                    { Name = "score1" Type = score target_score = 1000 } ... ] }
    ]
}

Mission paks (MISSIONS/<crc>.CHK = Missions/<name>/<name>.pak) hold <name>_goal_info + the goal's scripts, a node array <name>_NodeArray (restart points, trigger geometry with TriggerScript, game objects) and a sounds file. story_mode_goal_info (main pak, goal_info.qb) holds, per career goal, the presentation: intro camera (intro_presentation = { Template Camera = { LockTo = world Pos Quat FOV } }), the view-goals texts (view_goals_title, view_goals_presentation, view_goals_text_am/pro/sick), start_zone and trigger_Pos.

Tools

Callback names: <goal>_<checkpoint>_<tool>_<event> (m_hsfreeskate_chk1_timer1_expire, m_classic_houses_chkp1_high_scr_landedTargetScore), <goal>_<checkpoint>_enter / _exit (they get goal_id), and the script-side <goal>_post_activate _post_deactivate _post_load _post_unload _post_init _intro_post_load _pre_activate. Event suffixes in the executable: strings 0xCBA910..0xCBAE38.

Passing and failing: GMan_PassCheckpoint goal=<id> / GMan_FailCheckpoint (script wrappers that spawn the safe versions); passing the last checkpoint wins the goal. GMan_SetFlag goal tool flag value, GMan_IsFlagSet, GMan_SetGrade goal grade (0..3 = none, am, pro, sick), GMan_GetData / GMan_SetData, GMan_HasWonGoal, GMan_HasWonGoalThisTry, GMan_DebugBeatCheckpoint.

Starting a goal (goal_utilities.qb)

goal_create_goal_ped makes each ped_info entry: with Model a marker object (goal_create_non_ped_trigger: a composite object with motion, model, suspend, objectproximity, sound, hover and an optional compass blip; then create_script), without it a person (goal_script_peds_create_ped: CreatePedAtPos, proximity 10/15 m, an AI order). activates_goal entries get trigger handlers (goal_trigger_init_goal_trigger): inside 45 m (goal_utilities_trigger_radius_outer) the object glows (goal_trigger_far), inside 3 m (..._inner) a speech box "\m5 <prompt_text>" appears (goal_trigger_near); the square button (pad_option, verified in game) runs goal_accept_trigger: it checks goal_trigger_can_start_goal (no active goal, not locked, GoalManager_CanStartGoal, skater on the ground, no score pot, no menu), runs <goal>_pre_activate, an optional activate cutscene, then goal_accept_trigger_activate: PlayGoalPresentation when story_mode_goal_info.<goal> exists, GMan_DeactivateAllGoals, GMan_ActivateGoal.

The career's goal_infos_pakless goals (Nail the Trick) are the model for custom goals: a marker Model = "props/nail_marker/nail_marker.mdl", exists_in = both, activates_goal, prompt_text, CompassBlipType = goal, and enter_restart_pos in the checkpoint.

The pause menu (ui_pausemenu.qb) shows START / RETRY / END RUN for m_hsfreeskate in High Score mode and RETRY GOAL / RETRY LAST GOAL / QUIT GOAL otherwise.

Presentation (intro card and camera)

goal_presentation_play_guts {Template title dialog_text am_text pro_text sick_text grade Camera exit_script exit_params} (goal_presentation.qb) freezes the skater, plays an IGC camera (Camera = {LockTo = world Pos Quat FOV}), shows the title / description card with ACCEPT / QUIT, and on accept runs exit_script. Templates: goal_presentation_templates (dialog position; some play a Bink movie). goal_checkpoint_enter plays story_mode_goal_info.<goal>.checkpoints.<checkpoint>.presentation before the checkpoint's tools start.

Messages

HUD_message (ui_display_message / goal_ui_display_message) types: alert_signpost alert counter instruction instruction_general uberAlert alert_goal; goal_create_counter initial_count total_number hud_counter_caption (the "3 of 5 collected" counter); create_panel_message text style. Success: goal_success_messages = "<goal_text>: Goal complete" (uberAlert, green), fail likewise in red.

Gaps

Career gaps are binary assets per zone (zones/Z_Houses/Z_Houses.gap, loaded by career_gaps_startup). Scripts can also fire gaps the THUG way: StartGap GapID=<id> flags=[PURE_AIR | CANCEL_GROUND ...] and EndGap GapID=<id> text=w"..." score=<n> GapScript=<script> GapScriptParams={...} (skater member functions; gap_scripts.qb GetGap, the spot challenges' Chalk_StartGap / Chalk_EndGap). Mission node arrays call them from TriggerScripts of LevelGeometry nodes (m_classic_houses_trim_bush_gap04: StartGap flags=[PURE_AIR] trickscript=... then EndGap).

Collectibles and models

collect tool objects are GameObject nodes (Model = "gameobjects\skate\letter_s\letter_s.mdl", ...); goal_collect_init_object makes them spin, hover and raise AnyObjectInRadius -> goal_collect_got_object -> GMan_GotCollectObject. Every level load brings in pak/singleplayer/singleplayer.pak (stoken, bail / nail / chalk markers, get-there poster, historical markers, gap markers) and pak/multiplayer/multiplayer.pak (classic icon, secret tape, S-K-A-T-E and C-O-M-B-O letters, CTF flags): those models can be created anywhere with CreateCompositeObject (SetSearchAllAssetContexts around it).

In the game

Run in the native port (Houses, free skate from the main menu, which is the High Score mode singlesession), with the houses_goals example, test goals and goals.debug:

Things to know: a global initialized to the checksum none does not exist (the loader drops it); a won goal is uninitialized by the game and only initializes again with force_init (p8q_goal_start sets it; replay, on by default, brings the marker back); a previous goal's end-of-run reset can move the skater after the next goal's restart when goals are started back to back.

Place start markers more than 3 m from the free-skate start: the skater's walk-out passes them, and the level can then stay black behind the marker's prompt.

Not completed in the game yet: the trick, combo and score kinds with real input (the test harness's digital pad presses never landed a scoring trick: the score stayed 0; the goals start, show their HUD and time out correctly), and modes: career.

How Tony Hawk's Project 8 (BLUS30011) puts people in a level, and the kit's peds.* operations that add your own. Everything here was read from the game's own scripts and data. The status section lists what works in the native port; the rest is checked offline (it builds, parses back and compiles).

Where people come from

The kit uses the second way for people that stand or walk where you put them (a zone node is part of the zone, needs no goal and no script mod), the third for goal-givers (the goal system creates them) and for Lua (peds.lua).

The z_peds zone (the people heap)

ZONES/AE0D2CA4.CHK = z_peds.pak.ps3 (6,444,928 B) + ZONES/6957C973.CHK = z_peds_vram.pak.ps3 (24,692,736 B), loaded by load_level into the fixed PedParts heaps (main 6,656,000 B, video 25,088,000 B, limits.md) for every level (LoadPak "zones/z_peds/z_peds.pak" Heap = PedParts). It holds:

• 108 ped skins: the random-ped parts (RPed_* heads, torsos, legs), the goal peds (GPed_*), three pros (Hawk, Huston, Williams), Ped_RandomSkater_HEAD, ... A person can only be drawn in any level when every part of its profile is one of these (the kit calls such a profile resident; 125 of the game's 200 profiles are);
• z_peds_scripts.qb: the pedlife profile tables (global_pedlife_profiles, kid_pedlife_profiles, TouristM_pedlife_profiles, SkaterPeds_pedlife_profiles, ...): weighted lists of profiles, one per spawner;
• Z_Peds_NodeArray (.nqb, 2,065 nodes; compressed templates merged: 2,064 Interaction/POI, 1,279 Waypoint/PedAI, 777 LifeNode, 354 Interaction/Skate, 6 NavAllow). Names carry the level: Z_Peds_Houses_S_* (spawner), Z_Peds_Houses_I_* (interaction), Z_Peds_Houses_Sk8Ped* (skater path). Houses: 5 spawners, 22 interactions, 17 waypoints.

Level load (levels.qb): ParsePedLifeNodeArray Name = "zones/z_peds/z_peds.qb" once per level, and per zone ParseGlobalPedNodeArray ... zone = <zone> (Ped.qb: spawn_global_peds_in_zone, CleanupGlobalPedNodeArray on unload).

Ambient people (life peds)

{ Name = Z_Peds_Houses_S_Street01a02  Pos = (...)  Angles = (...)
  Class = LifeNode  Type = Generic  CreatedAtStart          (or CreatedFromVariable = NODEFLAG_...)
  ProfileName = kid_pedlife_profiles  Radius = 25.0  Num_Objects = 1  Area = Houses_Street01a }
{ Class = Interaction  Type = POI  CreatedAtStart  Area = Houses_Street02a
  UserData = AnimScript_MoveTo  Action = Act_Custom_Rest }

• The spawner script PedlifeSpawner keeps at most Life_Current_Max_Objects = 10 life peds alive. It spawns with SpawnAmbientObject { ped_type = ped_life } at a LifeNode chosen by default_spawn_params (40-55 m from the skater, out of view, 6 s cooldown); Pedlife_Refresh fills up to the cap at once (always_spawn_params). So ambient people appear out of sight and walk in.
• A life ped walks between the Interaction points of its spawner's Area and plays the point's UserData animation script there: AnimScript_GenMWallLean01, AnimScript_GenMIdles02, AnimScript_BumMSitFloor01, AnimScript_PedMTouristTakePic01, AnimScript_CopIdles, ... (120 AnimScript_* in the game, about 60 used). AnimScript_MoveTo = walk through the point. An AnimScript is Interact_MoveToAndBlock + Interact_Play...Anim calls (b9062e1a.qb), so they only work at interaction points.
• Composite objects (peds, props) come from the COIM pool: Generic_COIM_Size = 2,400,256 B in 8 KiB blocks, 250 blocks reserved for permanent objects outside classic mode; ShouldSpawnPed Priority = $COIM_Priority_PedLife asks it whether a life ped fits.

Profiles (appearance and behavior)

A profile is a global struct in the main script pak (8fc6e6ce.qb) that merges a creation-params struct:

RPed_Businessmen = { $human_creation_params  agent_stats = stats_civilian_kid
                     anim_profile = Businessmen_anim_profile  voice_profile = BusinessMan1
                     random_parts = [[RPed_businessmen_head], [RPed_businessmen_Torso], [RPed_businessmen_legs]] }
GPed_Jason_Lee   = { $goalped_creation_params  ped_body = { desc_id = GPed_Jason_Lee }  SkeletonName = GPed_JasonLee_skel ... }
Profile_Greg_Skater = { $human_creation_params  random_parts = [...]  scale = (0.93, 0.93, 0.93)
                        skateboard_profile = $skateboard_item_profile }
Pro_Hawk_Skater  = { $criticalped_creation_params  behavior_style = Bv_FixedPathSkaterPed  ped_body = { desc_id = Pro_Hawk } ... }

• random_parts: one list per slot (head, torso, legs, ...), each naming part tables (9cf0fa80.qb): arrays of { desc_id, mesh = "Models\\Peds\\Random_peds\\Businessmen\\RPed_businessmen_Head01.skin" }. The game picks one entry per slot (CreateRandomAppearance).
• ped_body / ped_board / ...: one fixed part, desc_id looked up in the global table of the same name (ped_body lists the pros, goal peds and cut-scene skaters; ped_board the props: golf club, camera, sign, ...).
• SkeletonName (Human or a goal ped's own, e.g. GPed_Dad_skel), sex, anim_profile (locomotion and reaction animations, 87ea66be.qb), behavior_style (Bv_Agent, Behavior_Blank, Bv_FixedPathSkaterPed, ...), agent_stats, voice_profile, skateboard_profile (the ped skates).
• A mesh is found by its file's base name among the loaded skins (Obj_InitModelFromProfile ... use_asset_manager = 1). The kit treats a profile as usable everywhere only when all its meshes are in z_peds.

Animations

Every person animation is in perm_anims.pak (PAK/170664B4.CHK, always loaded; 5,255 .ska, 942 for people): PedM_* (male, 360), PedF_* (female), PedMGen_* (walk cycles), PedMSk8* / PedMSk8r_* (skater peds), PedMBum_*, PedMCop_*, PedMTourist_*, PedMJudge_*, PedMKid_*, PedMWorker_*, GPed_* / gped_*. Goal peds use the human animations too (gped_anim_profile merges the default profile). Useful ones: PedM_Idle00_xx, PedM_ArmCrosIdle01_xx..05, PedM_Talk01_xx..11, PedM_Cheer01_xx..04, PedM_Clap01_xx..04, PedM_Laugh01_xx..04, PedM_Disappointed01_xx..09, PedM_CallSk8r02_xx, PedM_CheckWatch_xx, PedM_Looking01_xx..07, PedF_02_Cheer_xx, PedF_01_Clap_xx. The THAW-era names in some leftover scripts (Ped_M_Wave, Talk_Gesture_02, IGC_ped_*) do not exist in THP8.

Playing one on a person (THP8-era calls, from m_story_skateshop and goal_comp):

Behavior_ReplaceHierarchy { hierarchy = animation behavior = Behavior_PlayAnim
                            params = { anim = PedM_ArmCrosIdle01_xx orient_type = body cycle } }   ; loop
Behavior_ReplaceHierarchy { hierarchy = animation behavior = Behavior_PlayAnim params = { anims = [ PedM_Cheer01_xx ] } }
BlockUntilEvent Type = playanim_finished                                                            ; one-shot
AI_giveorder Name = Behavior_PlayAnim params = { anim = X event_id = Y }  +  BlockUntilEvent Type = Y

Movement and behavior (the agent system)

Peds are "agents" with behavior hierarchies (order, logic, life, animation, reaction, ...):

• AI_giveorder Name = <behavior> params = {...} (Agent_GiveOrder); Bv_Agent = the default life behavior, behavior_stand, Behavior_Blank, Behavior_LookAt { Object = Skater }.

• Walking: AI_giveorder Name = Behavior_MoveTo params = { Waypoint = <node> movement_desc = { movement = WALK_SLOW | WALK_FAST | run_slow | run_fast } finished_event_id = Move_Finished }, then BlockUntilEvent anytypes = [ Move_Finished Path_Blocked ] (the pattern of Interact_MoveToAndBlock). Behavior_FollowPath / Behavior_FollowPathNodes follow linked waypoints. Peds navigate on the zone's nav mesh (nav_ped, PEDMOTION_NAVMESH).

• Life mode: AI_giveorder Name = Bv_Agent + Agent_SetInteractAreas interact_mode = life interact_areas = [ <area> ] sends a ped to wander between the Interaction points of that area (how m_story_skateshop drives its peds).

• Reactions (bails, dodges): agent_stats (registered by RegisterAgentStatsStructures, 1412978d.qb) picks a damage block (323fbf71.qb) and a life behavior (ee7b176c.qb):

  stats	can be trampled	can be bumped	life behavior	used by
  stats_civilian, stats_civilian_kid	yes	yes (dodge, Bumped_Small/Big_*, knock-down)	Bv_LifePed	random peds
  stats_goal_ped	no	knock-down only	Bv_GoalPed	goal peds
  stats_critical_ped	no	no	Bv_LifePed	goal peds that must not be disturbed

  The animations come from the anim profile (Bumped_Small_F ..., Bumped_KnockDown_*, the PedM_Dodge*, PedM_Fall*, PedM_Bump* sets); trample reactions are LifePed_ReactToTrample_* (9d1e9b81.qb).

Placed Pedestrian nodes

{ Name = m_story_skateshop_trg_ped_g1_a2  Pos = (...)  Angles = (0.0, yaw, 0.0)
  Class = Pedestrian  Type = Generic_Ped | Goal_Ped | Ped_Global_Skater | Pro_Hawk ...
  CreatedAtStart  AbsentInNetGames  RenderToViewport  SelectRenderOnly  [IsSkaterPed]  [proximtrigger]
  PedAI_Type = Stand | walk | Skater   profile = RPed_Kid   SuspendDistance = 0  lod_dist1 = 80  lod_dist2 = 150
  [CompassBlipType = goal]  [TriggerScript = <script>] }

The node-object creator (sub_009125B4, called by ParseNodeArray and CreateFromStructure) handles Class = Pedestrian (and Ped) by pushing the "pedestrians" memory profile and calling sub_00898B2C:

• in the ped test level (load_z_test_nn) or for a node with the flag missionpakonly, the ped is built at once (sub_00898668: model from the profile, anim tree, ped logic, then the ped_init_skateboard script);
• otherwise sub_008716A4 turns the node into a spawn request for the composite-object manager (COIM): the profile, appearance, Name, Priority (default 0 = permanent) and Heap (default Generic) are packed and queued (sub_003CDAF4); with an extra_heap the ped is built directly in that heap.

293 Pedestrian nodes exist in the game (zones z_training and z_testlevel_peds, 40 mission paks); m_comp_parking creates 22 at once. Angles.y is the yaw in the kit's convention (the Houses start Angles = (0, 0.79, 0) faces the street, +X +Z).

In the native port, a Pedestrian node added to a zone node array with CreatedAtStart is not spawned (its spawn request is made, the ped never appears: the guest-memory search finds its position only in the node data); the same node with missionpakonly is built at once but stands in the bind pose (T-pose) unless a script animates it; a ped made with CreatePedAtPos from a script appears with its idle animation. The TriggerScript of a node or of CreatePedAtPos runs on the new ped (a diagnostic global set by it is found in memory). So the kit creates every placed person from the zone's setup script with CreatePedAtPos (below); mission paks keep using nodes.

Skater peds

Houses has one: the spawner Z_Peds_Houses_S_Sk8Ped01a00 (ProfileName = SkaterPeds_pedlife_profiles = Profile_Greg_Skater x2 / Skater_Female, Area = Houses_Sk8Ped01a) and two lines, each an Interaction (Type = Skate, Action = Act_SkatePath, in the area) linked to a chain of waypoints:

{ Class = Waypoint  Type = PedAI  CreatedAtStart  Continue  [JumpToNextNode]  PedType = Skate  Priority = Normal
  ContinueWeight = 1.0  SkateAction = Continue | Jump | Flip_Trick | Grab_Trick | Grind | manual
  [JumpHeight = 0.5]  [ManualType = manual]  [TerrainType = TERRAIN_DEFAULT]  Links = [<next node index>] }

The skater ped (a profile with skateboard_profile; Bv_FixedPathSkaterPed behaviors, Task_Skater) picks a line of its area, skates it doing the actions, and picks again at the end. m_story_skateshop puts a placed skater ped (Type = Ped_Global_Skater, IsSkaterPed, PedAI_Type = Skater) on a line of a mission area with AI_giveorder Name = Bv_Agent + Agent_SetInteractAreas interact_mode = life interact_areas = [ skateshop_school ]. Pros as skater peds: Pro_Hawk_Skater, Pro_Huston_Skater, Pro_Williams_Skater are resident (the other pros' skins are not in z_peds).

Goal-givers

A goal names its giver in <goal>_goal_info.ped_info:

ped_info = [{ Name = "m_story_dadhouses_Dad"  profile = GPed_Dad_Golfclub  areas = [StoryDadHousesArea]
              Pos = (-11.61, 2.64, -92.01)  Quat = (-0.0, -0.6708, -0.0)  exists_in = intro
              prompt_text = $str_...  activates_goal }]

The goal system creates it (also for pakless goals, goal_initpostload; an entry with Model becomes a marker object instead) through goal_script_peds_create_ped { ped_id profile Pos Quat [areas] [proxim_init_params] [behavior] [tags] [create_script create_params] }: CreatePedAtPos, Obj_SetOrientation Quat, Proximity_Init (the talk trigger: inner 10 m / outer 15 m by default, EnterProximityScript), Agent_SetInteractAreas, Agent_GiveOrder Name = <behavior> (default Bv_Agent), then <create_script> <create_params>. Quat is the vector part of the orientation quaternion (w implied, positive); the game reads it as the inverse of the usual right-handed rotation, so a yaw a (local +Z -> (sin a, 0, cos a), like Angles.y) is Quat = (0, -sin(a/2), 0) (in game: (0, +sin(112.5), 0) faced 135 degrees). The goal side (prompt, talk trigger, camera) belongs to the quests ops; the kit's peds.add kind goal_giver provides the person and hands the entry over (below).

Limits

Each placed person adds about 300 B of node data and 300-900 B of scripts to the zone's header pak (the Houses example with five people: +5,120 B).

The operations

All in tools/modkit/ops_peds.py (PHASE 50: before the goals ops). Coordinates are world space (Y up, meters); yaw in degrees about +Y, local +Z -> (sin yaw, 0, cos yaw), the same as every other op. A person's name is its node name and its run-time object id (Lua: qb.call(fn, params, name)), used as given: give it your own prefix.

peds.add

What each kind makes (in the zone's <zone>_scripts qb, plus path nodes in its node array):

• every person except a goal-created giver: <name>_Spawn, called last by the zone's setup script <zone>_Setup (run by levels.qb after the zone's node array is parsed, each time the zone streams in; the kit adds the call, or the script if the zone has none): if not isCreated <name> -> CreatePedAtPos Pos Quat Ped = <name> profile TriggerScript = <name>_Script [CompassBlipType = goal] [ped_skates = 1]. <name>_Script (run on the new ped) spawns <name>_Life: stats, look-at, then the kind's behavior;
• stand: <name>_Life plays the idle animation loop (or the random sequence);
• walker, mode: follow (default): Waypoint nodes <name>_wp<i> linked in order (and back to the first for a loop); <name>_Life stops the agent's AI (Behavior_Blank) and calls <name>_WalkTo waypoint = <node> for each: turn to the node (Obj_LookAtPos at the ped's own height), play the profile's walk cycle (its anim profile's Move_Ground_Walk_F) and move with the game's scripted mover (Obj_MoveToPos <pos> speed = N mph + Obj_WaitMove, as its goal and AI scripts do), then play idle_at_points. mode: wander: the same, to a random point each time, idling there. The game-AI modes path (Behavior_FollowPath over the nodes) and life (Interaction points in area <name>_area, the ped in life mode) are kept, but they did not move script-spawned people in free skate;
• skater, mode: script (default): an Interaction (Skate, Act_SkatePath) <name>_line + Waypoint/PedAI nodes <name>_sk<i> with the actions (continue, ollie, jump, flip, grab, grind, manual); <name>_Skate rides from point to point (the skateboard object, Agent_GetVehicle, when the ped has one, else the ped) with the push cycle PedMSk8_PushCycle_xx at 9 mph and plays the action's skater-ped animation at each point (PedMSk8_Ollie_xx, PedMSk8_KickFlip_xx, PedMSk8_MuteInvertINIT_xx, PedMSk8_5050slow_xx, PedMSk8_ManualRange_xx). mode: ai: the game's skater-ped AI (created on its board, life mode over <name>_area: Task_Skater follows the PedAI waypoints and does the SkateActions); it did not move a script-spawned ped in free skate;
• goal_giver, spawn: goal (the default when goal is set): no spawn script; <name>_Create (spawns the idle loop on the giver) and the ped_info entry for the goal op: ctx.goal_givers[name] = {"goal", "ped_info_qb": "{ Name = \"<name>\" profile = ... Pos = (...) Quat = (0, -sin(yaw/2), 0) create_script = <name>_Create create_params = { ped_id = <name> } }"} (also ops_peds.goal_giver_entry(ctx, name)); spawn: script (no goal): spawned like a stand person, with the goal blip on the compass;
• a custom profile adds <name>_profile: the base profile's items written out (its merges expanded) with each chosen part set under its stock part-table key, RPed_businessmen_head = { desc_id = Businessmen_Head03 }, and random_parts kept only for the slots left out. The ped model builder (create_ped_model_from_appearance = ForEachInEditableList ModelAddGeom) draws only the part keys of the global ped_editable_list (51 keys, registered at startup), so a part stored under any other key is never drawn (in game: a first version with tables of its own made headless people). The build refuses a part whose table is not in that list.

{"op": "peds.add", "zone": "z_houses", "name": "ex_ped_suit", "pos": [-60.13, 2.39, -65.16], "yaw_deg": 225,
 "profile": "RPed_Businessmen", "anim": "PedM_ArmCrosIdle01_xx"}
{"op": "peds.add", "zone": "z_houses", "name": "ex_walker", "kind": "walker", "profile": "RPed_Kid",
 "path": {"points": [[-57.2, 0.3, -57.8], [-54.3, 0.3, -60.6], [-52.2, 0.2, -58.5], [-55.0, 0.2, -55.7]]},
 "idle_at_points": [null, "PedMKid_Idle02_01_xx", null, null]}
{"op": "peds.add", "zone": "z_houses", "name": "ex_skater", "kind": "skater",
 "path": {"points": [[-59.6, 0.2, -46.1], [-55.4, 0.2, -50.4], [-51.2, 0.2, -54.6], [-46.9, 0.2, -58.9]],
          "actions": ["continue", "continue", "ollie", "continue"]}}

peds.remove

{"zone", "name"}: a Pedestrian node (stock or added) is no longer created (its CreatedAtStart / CreatedFromVariable is dropped; the node stays, so no index moves). {"zone", "area"}: the zone's ambient spawners of a z_peds area; {"zone", "ambient": true}: all of them (edits z_peds, checked against the PedParts heap). peds.ambient {"zone", "enabled": false} is the same as the latter.

peds.replace_appearance

{"zone", "name", "profile"}: another profile (or {"base", "parts"}) for a Pedestrian node. {"table": "<pedlife table>", "profiles": [{"profile", "weight"}]}: what a z_peds pedlife table spawns (e.g. make every Houses street kid a tourist: kid_pedlife_profiles).

Editor and catalog

ops_peds.SCHEMA (property panels, gizmos: pos position, yaw_deg yaw, path.points path, marker ped) and QUERIES:

• peds.catalog -> {profiles: [{name, kind, resident, skeleton, sex, anim_profile, behavior, skates, scale, slots: [{slot, tables, choices: [{desc_id, mesh, resident, bytes}]}], fixed, thumb?, glb?}], anims: [{name, category, loops}], anim_scripts, pedlife_tables, skate_actions, speeds, kinds, limits};
• peds.stock {zone} -> the zone's placed peds, ambient spawners, interaction points and skater lines.

python tools/modkit/peds_catalog.py [--thumbs] [--glb] [--only resident] writes the same JSON plus thumbnails (textured bind pose, rendered with the kit's renderer) and one .glb per part, from the player's own game files, into work/peds/catalog (nothing of the game goes into a mod or the repository).

Lua (modapi)

tools/modkit/lua/peds.lua, shipped by modapi as the built-in library peds: peds.spawn(id, profile, pos, yaw_deg, {anim, react, skates, blip, behavior}), peds.remove, peds.teleport, peds.face, peds.play_anim(id, anim, {loop}), peds.idle, peds.wait_anim, peds.walk_to(id, node | object | {x, y, z}, {speed, wait, object, anim}), peds.look_at, peds.stop, peds.skate_line(id, area), peds.mover(id). A person whose profile has a skateboard (Profile_Greg_Skater, Skater_Female, Pro_*_Skater) stands on its board, an object of its own (Agent_GetVehicle): moving the ped does nothing, so walk_to and teleport move peds.mover(id) (the board, or the ped itself when it has none). In game, a Lua-spawned Profile_Greg_Skater walks to a position or a node and can be teleported, and a zone-script RPed_Businessmen moves with every method (walk_to to a position or a node, Obj_MoveToPos, Obj_MoveToRelPos, Obj_SetPosition).

Talk prompts: peds.talk(id, {name, prompt, radius = 4, pos, once, on_talk = function(id) ... end}), peds.untalk(id), peds.talking(id), peds.near() (the id whose prompt is up). While the skater is within radius of the person (its pos, or its own position re-read twice a second, so walkers work), on the ground and not in a trick, the stock-look prompt ": (button)" shows at the bottom of the screen (create_speech_box, the box the game's talk prompts use); Circle (the glyph) or Triangle talks: on_talk(id) runs in a task of its own and the event peds_talk {id} is emitted; once removes the prompt after one talk; the nearest person wins. The game's own trigger (setup_ped_speech) does not fire for people made by a zone setup script or by Lua in free skate, so this is the one prompt implementation for every mod (the story runtime uses it). Offline test: tools/modkit/tests/peds_lua_test.lua (any Lua 5.4).

Status

Offline, every kind builds into z_houses, parses back, and its scripts compile and decompile (tools/modkit/tests/test_peds.py). In the native port, in free skate in Houses:

The stock talk trigger setup_ped_speech (AnyObjectInRadius on the ped) never fires for people made by the zone setup script in free skate, so a talk prompt for such a person must be drawn by a script of its own (peds.talk does this). The goal-giver path (spawn: goal, the goal system's own proximity trigger) does show its prompt. A random-parts profile (Profile_Greg_Skater, RPed_*) gets a new look every load; for a fixed look give every slot a part ("parts") or use a one-body profile (GPed_*).

Not yet tested in game: peds.replace_appearance on a pedlife table or a mission ped, react: true reactions (bumps, knock-downs), pros other than the three resident ones (allow_streamed), more than 8 people at once. more than 8 people at once.

Every operation is one entry of the ops list of a mod manifest: a JSON object with "op" and the parameters below. python tools/modkit/modkit.py ops lists the operations your copy of the kit provides.

Rules that hold for every operation:

• Paths (source, gltf, image, ...) are relative to the mod folder, for example assets/ramp.glb. An absolute path, or one that leaves the folder, is an error.
• Unknown parameters. The static, texture and skin operations reject a parameter they do not know and list the ones they accept, so a typo cannot silently do nothing. The collision and nodes operations ignore parameters they do not know: check the spelling against this page (yaw_deg, rotation_y, ...). Keys that start with _ or x_ are comments and are removed before the operation runs.
• Order matters. The operations of a build run in load order (packaging.md); each one sees the files as the earlier ones left them. Collision operations that name a static object ("object": "modkit_kicker") must come after the static.add_object that made it.
• Failure writes nothing. The first error stops the build; the installed pack stays as it was.
• Coordinates are game world space: Y up, right-handed, meters. rotation_y and yaw_deg are degrees about +Y; a yaw of 0 leaves local +Z pointing at world +Z, and a positive yaw turns local +Z towards +X (local +Z becomes (sin yaw, 0, cos yaw)).
• Budgets are checked after the operation and recorded in the build report (limits.md).

All the objects of one mod are named by you. The game only knows names by their checksum, so choose a prefix of your own (modkit_, mymod_) and keep it unique within the zone.

Contents: static: add_object, replace_object, replace_mdl, remove_object | texture: replace, recolor | skin: common parameters, replace_mesh, replace_part, add_mesh, recolor, replace_texture, deck_graphic, griptape, cas_texture | collision: add_mesh, add_box, add_ramp, remove, copy | rails: add, remove | nodes: add_rail, add_gameobject | goals

How the operations are checked: the build runs, every rebuilt file parses back, the example mods render correctly in the kit's own renderer, and each area runs in the native port; the overview lists what works in game and the known limitations.

---

static

Geometry of zones (levels) and props. glTF in; the game's .geom / .mdl geometry, the material and texture dictionary entries it needs, and the zone's node entry out. Library: tools/models/import_static.py.

How an import turns glTF into game data: each glTF primitive (one per material) becomes one game mesh, split automatically when it exceeds 32,767 vertices or 65,535 strip indices. The vertex format is the template mesh's (position, packed normal, tangents, color, half-float UVs). A glTF material gets a game material cloned from a template of the same kind (opaque, cut-out, blended), its own texture is added to the zone's texture dictionary, and a neutral normal map fills any normal-map slot. See blender.md.

Parameters shared by static.add_object, static.replace_object and static.replace_mdl:

static.add_object

Adds a new object to a zone: a ramp, a rail, a box.

If any of position, rotation_y, scale is given, the glTF node's own transform is ignored and the node's mesh (in its local space) is placed by them. Without them the glTF world transform is the placement, as an object's position in Blender is. The operation records the placed object (world triangles, bounding box) for the collision operations that follow it.

{"op": "static.add_object", "zone": "z_houses", "name": "modkit_kicker", "source": "assets/ramp.glb",
 "node": "modkit_kicker", "position": [-61.05, 2.39, -64.52], "rotation_y": 45, "snap_to_ground": true}

Game models. With game_model the kit exports the model from your game files to a temporary glTF at build time (base-color textures embedded, the material references kept) and imports it like any other source; the file never enters the mod folder. A prop needs position (its model space is around its own pivot, usually the bottom center). A zone object without position / rotation_y / scale is duplicated in place, at its original spot. Materials the target zone already has (a zone object copied within its own zone) are reused as they are; others (every prop material) become clones of a zone material of the same kind with the model's own base-color texture, which adds that texture to the zone (the budgets show the growth). Collision is not copied: add it with a collision.* operation.

{"op": "static.add_object", "zone": "z_houses", "name": "mymod_propane", "game_model": "GO_PropaneTank",
 "position": [-61.0, 2.39, -64.0], "rotation_y": 30, "snap_to_ground": true},
{"op": "static.add_object", "zone": "z_houses", "name": "mymod_mailbox",
 "game_model": "z_houses:Z_Houses_Street_JG_MailBox04", "position": [-62.5, 2.39, -63.0], "rotation_y": 90}

The object has no collision until a collision.* operation gives it some, and it exists only in the full zone, not in the distant _lod stand-in (limits.md).

static.replace_object

Swaps the meshes of an existing zone object for those of a glTF node. The object keeps its name, node and collision; you can add or remove meshes inside it.

{"op": "static.replace_object", "zone": "z_houses", "object": "Z_Houses_Street_JG_FlowerRing01",
 "source": "assets/ring.glb", "node": "modkit_ring", "lightmap": "object"}

Collision stays the old object's. If the shape changed, remove the old collision with collision.remove and add the new with collision.add_mesh.

static.replace_mdl

Replaces a prop (a .mdl model such as GO_PropaneTank) in every pak that holds it, so every place that prop appears changes.

A prop is replaced as a whole: a model with several objects keeps only the first, the others lose their meshes. Lightmaps are neutral (props are lit dynamically).

static.remove_object

Hides a zone object: its meshes are removed; its record, node and collision stay.

static.clear

Hides every object of a zone: a blank canvas for a park built from scratch (the level editor's "New park from scratch"). Objects added earlier in the same build are kept, so put it after your static.add_object ops: the importer clones the zone's own materials as templates, which a cleared zone no longer offers.

Hiding the largest zone's geometry also shrinks its _vram pak, which frees video memory for every level (limits.md). Pair it with collision.clear and rails.remove all, or the skater still hits and grinds the invisible level.

---

texture

Any texture of the game, by dictionary entry. A texture is found by its checksum (8 hex digits, the form the kit's exports use in their image names) or its name. Library: tools/tex/texdict.py.

texture.replace

Puts your picture in place of a game texture. The size may change (the dictionary entry, the mip chain and the pixel data are rebuilt together).

Sizes that are not powers of two are resized to the nearest power of two (at most 2048); the mip chain is generated; cube and volume textures are not supported. The operation changes every container of the pak that holds the texture and fails if the texture is not there.

{"op": "texture.replace", "pak": "z_houses", "texture": "794d6ffd", "image": "assets/drywall.png"}

texture.recolor

A build-time color edit of a game texture, so a mod ships parameters instead of game pixels. The texture is decoded from the player's own game files, changed, and encoded again.

At least one of hsv, tint, colormap is required. The steps run in the order colormap, hsv, tint; alpha is kept.

{"op": "texture.recolor", "pak": "z_houses", "texture": "794d6ffd", "hsv": [200, 1.0, 1.0]}

For skater textures, which are shared atlases, use skin.recolor: it finds the texture through the model and changes only the texels one mesh uses.

texture.overlay

Paints over a game texture with a layer of your own (graffiti, a logo, scuffs): the mod ships only the layer, a PNG with transparency; the build composites it onto the player's copy of the texture.

{"op": "texture.overlay", "pak": "z_houses", "texture": "794d6ffd", "image": "assets/tag.png", "opacity": 0.9}

The level editor's texture tools write this op ("Paint over...").

---

skin

Skinned models: skaters, create-a-skater (CAS) clothing and accessories, boards, deck graphics. Library: tools/models/import_skin.py. Units and axes are the kit's export space: game model space, Y up, meters, the skater faces +Z, the board's nose is +Z.

Common parameters

Free skate, skater select and create-a-skater draw a pro from the cas_shared pak, not from his standalone files, so the default is right for most mods.

skin.replace_mesh

Replaces game meshes with glTF meshes, normally ones exported by the kit and edited in Blender (modkit.py export skater pro_hawk, blender.md).

Bones are matched by name (case-insensitive; bone_<crc8> for unnamed bones); weighted joints the game skeleton does not have fail the import with the list. At most 3 weights per vertex are kept (the largest, renormalized). Meshes whose vertices, normals, weights and triangles did not change keep their bytes. A changed mesh is rebuilt; if it is over the SPU skinning budget it is split automatically unless allow_ppu.

{"op": "skin.replace_mesh", "skin": "Pro_Hawk", "gltf": "assets/hawk_head.glb", "node": "Pro_Hawk_head"}

skin.replace_part

Same parameters as replace_mesh, plus hide_missing (default true), template (a mesh index: descriptor donor for new meshes) and material. The glTF is the whole model: primitives that map to a game mesh replace it, the others are added as new meshes, and game meshes that are not in the glTF are hidden (one degenerate triangle) unless hide_missing is false. A whole-character replacement on Tony Hawk's slot works.

skin.add_mesh

Adds a mesh to a skinned model.

{"op": "skin.add_mesh", "skin": "Pro_Hawk", "gltf": "assets/cap.glb", "node": "modkit_cap",
 "rigid_bone": "Bone_Head", "offset": [0, 0.03, -0.012], "scale": 1.1}

The new mesh draws after the mesh it copies its descriptor from. It adds a material and a texture of its own to the model's texture dictionary.

skin.recolor

Recolors the texture(s) of a skinned model at build time.

{"op": "skin.recolor", "skin": "Pro_Hawk", "mesh": 4, "hue": 150, "saturation": 1.9, "value": 1.35}

skin.replace_texture

Puts your picture on a skinned model's texture.

skin.deck_graphic

Replaces a skater's deck graphic. A pro's deck graphic is a texture swap of the CAS system (the Board's default deck texture is replaced by Decks_X); this edits that swap image.

The deck graphic is a portrait picture, u across the deck and v along it. One of skater or deck is required. Tony Hawk's graphic is the 128 x 256 DXT1 image Decks_Birdhouse_01; the size is kept unless you give size.

{"op": "skin.deck_graphic", "skater": "Hawk", "image": "assets/deck.png"}

skin.griptape

The same for the griptape slot: image, skater or desc (Generic 1, Grip_Zombie, Grip_VooDoo), fit, rotate, size.

skin.cas_texture

Any CAS texture-swap list: slot (e.g. deck_graphic, griptape) plus desc or skater, image, fit, rotate, size. deck_graphic and griptape are shortcuts for it.

---

collision

New solid surfaces in a zone's collision (Havok .hkc). The visual geometry of an object and its collision are separate data, so these operations add collision only: pair them with static.add_object to see what you hit. See collision-rails.md for what the game does with them and what is not supported.

Common parameters:

Limits per operation: 65,535 triangles and 65,535 vertices; 254 distinct material words.

collision.add_mesh

A triangle mesh as collision.

{"op": "collision.add_mesh", "zone": "z_houses", "object": "modkit_kicker"}

collision.add_box

A box.

{"op": "collision.add_box", "zone": "z_houses", "object": "modkit_rail", "yaw_deg": 45}

collision.add_ramp

A parametric kicker, without needing a mesh.

collision.remove

Takes the collision bodies of a node (stock or added) out of the zone: zone, name. Use it after static.replace_object changed an object's shape, then add the new shape.

collision.clear

Takes every collision body of the zone out: zone, and keep (node names, or prefixes ending in *). Bodies added earlier in the same build are kept: put it after your collision.add_* ops. (rails.remove all, in contrast, goes before your rails.add ops.)

collision.copy

Copies the collision of an existing node as a new body: zone, from (the node, e.g. Z_Houses_g_nuclear_kicker), name, offset [dx, dy, dz], rotation_y (degrees about pivot, default the source's base center), pivot. Boxes and cylinders of the source become convex hulls. Useful to clone a stock ramp where you want one.

---

rails

Grind rails the game really builds. In the retail game (script global RAILNODE_ASSETS_ENABLED = 1) the rails of a level come from pak/global_rails/global_rails.pak: one baked .rnb_lvl file per zone, loaded once per level. The zone's node array also lists every rail point as a RailNode node, but the game only reads those by name (scripts) and in the park editor. rails.add writes both, like the game's own tools did. Format, loader and limits: collision-rails.md; library tools/models/thp8rnb.py. Seen working in the game: the skater grinds a rails.add rail, and a rail only in the node array is not built (what is verified).

rails.add

Adds a grind rail: a polyline the skater can snap to and grind along. Rails are not collision: a rail has no surface of its own, so give it a visual (static.add_object) and, if it must be solid, a collision body.

The rail line is one of:

Other parameters:

{"op": "rails.add", "zone": "z_houses", "name": "p8rail_line", "cluster": "p8rail", "terrain": "MetalPole",
 "points": [[-54.3335, 0.539, -57.806], [-50.798, 0.539, -54.2704]]}

A rail needs at least two points; no segment may be shorter than 5 cm. One operation per rail: a level editor turns each drawn or generated rail (coping, ledge edge, funbox rail) into one rails.add with its world points.

Budget: the rails of all zones share RailNodeHeap (1,761,280 bytes; the stock global_rails.pak uses 1,742,848 of them once padded), so about 150 rail nodes fit before the build raises the heap: rails.add then sets the heap size in the startup script in 64 KiB steps (a warning; at most 1 MiB over the stock size, taken from main memory). The build report records RailNodeHeap (global_rails.pak).

rails.remove

Removes rails from a zone's baked rails (the records the game grinds on). zone and one or more of:

The points' neighbors are unlinked, so what is left of a cut rail ends there. The nodes stay in the node array (scripts may name them; the game builds no rail from them). Order matters as everywhere: all removes the rails added by earlier operations unless keep names them, and does not touch rails added after it.

{"op": "rails.remove", "zone": "z_houses", "name": "Z_Houses_NxSpline_76_KNOT_0"}
{"op": "rails.remove", "zone": "z_houses", "all": true, "keep": ["p8rail_line"]}
{"op": "rails.remove", "zone": "z_houses", "within": {"center": [-60, 3, -63], "radius": 6}}

---

nodes

Entries of the zone's node array (the .nqb): the data that scripts and the engine read to place and wire things.

nodes.add_rail

The same operation as rails.add, with the same parameters (kept so existing mods and editor projects build unchanged; new mods should write rails.add).

nodes.add_gameobject

Places another copy of a game object that the zone already has (a barrel, a bin) by cloning its node.

The object's model must already be loaded in that zone: you place more of what the zone has, not new models (use static.add_object for a new model).

nodes.set

Moves or turns an existing node: a restart point, a game object, a trigger.

{"op": "nodes.set", "zone": "z_houses", "node": "Z_Houses_TRG_Restart_Default", "pos": [-60, 2.39, -60], "yaw_deg": 90}

The free-skate start of a level is its ..._TRG_Restart_Default node, so this moves where free skate begins.

nodes.add_restart

Adds a restart point (a copy of one of the zone's restart nodes).

---

peds

People: peds.add (kinds stand, walker, skater, goal_giver), peds.remove, peds.replace_appearance, peds.ambient. The full reference, with what the game does underneath, is peds.md.

{"op": "peds.add", "zone": "z_houses", "name": "mymod_suit", "pos": [-60.13, 2.39, -65.16], "yaw_deg": 225,
 "profile": "RPed_Businessmen", "anim": "PedM_ArmCrosIdle01_xx"}

---

goals

Custom goals (quests) for the free-skate world: goals.add_score, goals.add_combo, goals.add_collect, goals.add_race, goals.add_gap, goals.add_trick, and goals.debug for test builds. They have their own page, goals.md: every parameter, how goals start (marker, person, pause menu, script), chains, the intro presentation, the runtime scripts and results for Lua and stories, and how the game's goal system works.

{"op": "goals.add_collect", "name": "myname_street_tokens", "title": "Street Tokens", "text": "Grab all 5 tokens!",
 "pickups": [[-54.68, 1.1, -58.15], [-52.56, 1.1, -56.03], [-50.44, 1.1, -53.91]], "model": "stoken", "time": 60,
 "start": {"trigger": "marker", "pos": [-57.51, 0.19, -55.33], "yaw": 45, "model": "chalk"}}

---

music

Custom soundtrack: music.add, music.folder, music.replace, music.disable, music.options. The full reference, with how the game plays music, is soundtrack.md.

{"op": "music.add", "file": "assets/my_song.ogg", "artist": "Me", "title": "My Song", "genre": "Punk"}