Load ZIP mod packages and publish agent authoring guides and packaging tools

docs/lua-modding.md

@@ -1,21 +1,30 @@
 # Lua modding SDK 1
 
-This is an implemented, in-process Lua 5.4 SDK for this engine. Open **Escape/Start → Mods**. New packages are disabled. Select a package to enable/disable, reload, edit settings or reset defaults. Up/down and D-pad scroll eight visible rows; left/right changes booleans, numbers and choices; Enter/A chooses. Strings use keyboard text entry, Backspace, Enter to commit and Escape to cancel. B/Escape returns one level without resuming behind the menu. The existing map, marker, bail and character menus remain the owners of their native behavior.
+Start with [the agent instructions](../sdk/AGENTS.md) and [ZIP package guide](mod-packages.md).
+Use `PLAY-MARIO-KART.bat` / `Build-VehicleSDK.ps1` for the current integrated build;
+older named trainer/window launchers are historical snapshots. The project launcher
+loads top-level `mods/`, starts paused, and writes `.local/vehicle-sdk/session.log`.
+Prepared engine assets are required; Lua itself is embedded.
 
-Run `PLAY-NATIVE-TRAINER.bat` for the current trainer build (`Build-NativeTrainer.ps1` builds it); `PLAY-LUA-SDK.bat` retains the earlier SDK build. It starts paused, uses isolated mod preferences, and writes `.local/lua-sdk/session.log`. It requires prepared engine assets and the executable generated by `Build-LuaSDK.ps1`. Set `SKATE3_ASSETS` or the private `.local/lua-sdk/assets.path`; the checked-in launcher contains no personal installation path. No Lua installation is needed.
+Open Escape/Start → Mods. New mods start disabled. Each has a red DISABLED or green
+ENABLED badge and explicit enable/disable action. Enabled mods have separate movable,
+resizable and collapsible settings windows with continuous scrolling and a scrollbar.
+The ordinary pause menu stays centred. Minus/plus controls change values; Tab/controller
+X cycles focus, arrows/D-pad select/adjust, and strings open the text editor. Changes
+are saved outside the package. Window layout is retained for the current process.
 
 ## Quick start
 
-Copy `mods/native-trainer` to another immediate child of `mods`, change its `id` and `name`, then choose Rescan packages. A package consists of:
+Copy `sdk/examples/native-trainer` into a new authoring folder, change its `id` and `name`, then package it with `tools/package_mod.py`. A ZIP contains:
 
 ```text
-mods/my-mod/
+my-mod.zip (archive root)/
   mod.json
   main.lua
   assets/             # optional original text data or authored body clip JSON
 ```
 
-`SKATE3_MODS` overrides the discovery directory; its default is the top-level `mods` folder **beside the running game executable**, independent of the working directory. The engine creates it if absent and logs its full path; the Mods list has an **Open mods folder** action. Only immediate child directories are packages. Archives are not loaded. `SKATE3_MOD_SETTINGS` overrides the writable preferences directory; the default is `settings/mods` beside the engine asset directory. Keep preferences outside packages.
+`SKATE3_MODS` overrides the discovery directory; its default is the top-level `mods` folder **beside the running game executable**, independent of the working directory. The engine creates it if absent and logs its full path; the Mods list has an **Open mods folder** action. Immediate `.zip` files and non-hidden development folders are packages. ZIPs require mod.json at their root and are extracted automatically into a session cache. `SKATE3_MOD_SETTINGS` overrides the writable preferences directory; the default is `settings/mods` beside the engine asset directory. Keep preferences outside packages.
 
 A minimal manifest:
 
@@ -94,7 +103,11 @@ Polling occurs at most every 500 ms and hashes bounded package contents (not jus
 
 Successful world changes remove **all** mod objects and animation overrides before `world_changed` is delivered. Lua locals, settings and timers survive this event. Rebuild world-specific objects in the callback, cancel any world-specific timers, and clear stored positions when retaining world-specific positions. `sdk.snapshot.map.generation` identifies the current world, including reloading the same map. Failed map preparation retains the previous world and emits no world-change event.
 
-## Complete SDK API
+## SDK API
+
+The callable names/signatures are also in [sdk/skate.lua](../sdk/skate.lua).
+Vehicle commands, collider/mass/audio configuration and rider slots are documented
+in [vehicle-sdk.md](vehicle-sdk.md). Trainer tuning is documented below.
 
 All vectors are 1-based Lua arrays `{x,y,z}` in engine world coordinates, metres, Y up. All API functions below use dot calls, not colon calls. Mutable snapshot/settings tables are per-state copies: editing them does not mutate the engine. Retained snapshots are stale; query again inside callbacks.
 
@@ -183,7 +196,14 @@ Only install mods from authors you trust. Isolation is an engine fault-containme
 
 Each Lua allocator is limited to 8 MiB and each entry evaluation/invocation to approximately 101000 VM instructions (hook every 1000 instructions). A long-running C library operation does not execute VM hooks; parsing, garbage collection, file I/O and host work are not hard wall-clock bounded. Aggregate mod load can still lower frame rate. There is no process isolation, hostile-filesystem race defense, hard timeout for native operations or guarantee against implementation bugs in dependencies. Package paths reject traversal and absolute paths, canonicalize within the root and reject escapes. Symlink entries are rejected during scanning; do not use junctions/links in mods. Do not mutate package trees maliciously while reading them.
 
-Discovery inspects at most 128 sorted immediate directories; packages over 512 files/directories or 8 MiB of file data are rejected. Keep packages small. Lua allocator quotas do not include Rust/Bevy asset storage; visual count and package/file limits bound those separately. Source and plain UTF-8 data can be loaded with `sdk.read_text`; there is no general JSON decoder/import loader in Lua. Prefer ordinary Lua local functions and source literals for small data. Body JSON has its dedicated engine parser. This release does not load mod GLTF/meshes, textures, fonts, audio banks or general Bevy scenes. Cubes are original generated geometry and text uses the engine's existing font. Do not ship private Skate maps, banks, extracted character assets, sounds or captures; mods can rely on the player's installed engine data for allowed body slots without copying it.
+Discovery inspects at most 128 sorted immediate packages (ZIPs or development folders).
+Packages are limited to 512 files/directories and 64 MiB; ZIP compressed/expanded bounds
+and path rules are in mod-packages.md. Lua allocator quotas exclude host asset storage,
+which is bounded separately. `sdk.read_text` reads UTF-8 package data; there is no general
+JSON decoder in Lua. Vehicle definitions and native animation JSON use dedicated host
+parsers. Vehicles support embedded GLB models and synthesized engine audio. Arbitrary
+scene/texture/font/audio-bank loading is not exposed. Text uses the existing engine font.
+
 
 No camera-controller override, native audio command, customiser-profile mutation, physics force injection, collision-geometry insertion, climbing controller installation, map-selection command, score manipulation, networking, cross-mod messages or persistent Lua save store is exposed in API 1. Existing character customisation, native audio integration and private climbing loaders retain their own lifetimes. Broad engine-internal access is deliberately absent. Useful current extension types include HUDs, timers, route/training challenges, native-reset navigation tools, visual world annotations, grind/bail instrumentation and constrained original body animation replacement.
 
@@ -191,92 +211,35 @@ The runtime pins `mlua = 0.12.1`, with `lua54`, `vendored`, `serde`, `send`; Car
 
 Distribute your package directory with source, original permitted data, a license/readme and engine/API requirements. Ship no preferences, local paths, dependency cache, executable or game assets. New compatible SDK functions may be added under API 1; removing/changing existing signatures requires a new API major. Unknown callback names and manifest fields are rejected now, so adding them to an old host fails visibly. Lua/package errors are visible under the selected mod; directory/schema errors are on the list page. If a hot edit fails, fix it and save or Reload. Reload and settings changes are intentionally usable while gameplay is paused.
 
-## Validation and manual test checklist
+## Validation and build
 
-`cargo test --locked -p skate-mods --target x86_64-pc-windows-msvc` runs the standalone window-free Lua/schema suite. It covers the bundled Native Trainer, reload state reset, timers/replacement/order, settings persistence and validation, duplicate IDs, removal/invalid manifests, path restrictions, failure isolation, unload failure, instruction and memory limits. This is not rendered-gameplay validation.
+```powershell
+cargo test --locked -p skate-mods -p skate-vehicles
+cargo run --locked -p skate-mods --example check_mod -- path/to/mod.zip
+python tools/package_mod.py sdk/examples/native-trainer mods/native-trainer.zip
+```
 
-Use `Build-LuaSDK.ps1 -DependencyTargetDirectory <shared cargo cache>` to produce a uniquely named direct linker output, check SDK/CLI diagnostic strings without executing it, and record a staged SHA-256. Do not copy the generic executable from a shared Cargo target. `PLAY-LUA-SDK.bat` is provided exclusively for the user's manual run. No game, recomp, game asset-check mode, automated controller input, screenshot capture or game-based validation was executed for this SDK task.
+The checker validates package bounds, manifest/settings and Lua syntax. It does not
+execute callbacks, launch gameplay, or prove native animation/handling correctness.
+ZIP integration tests cover asset reads, replacement, deletion, duplicate IDs, invalid
+paths and expansion limits. Validate in-game behaviour manually after the headless checks.
 
-Manual checks still required: open/scroll/back with keyboard/controller; enable Native Trainer; edit all setting types; hot-edit and reload; deliberately cause a Lua error then recover; add/remove/duplicate a package; disable and verify HUD/cubes disappear; switch maps and check marker/customiser/bail behavior; adjust pop/push settings, then disable and check stock behavior; inspect original authored animation replacement if available. Teleport destinations and animation visuals require deliberate author testing. Compilation and window-free runtime tests do not establish these gameplay results.
+## Native trainer and examples
 
-Integration footprint: `skate-mods` owns VM/schema/discovery/preferences; `skate-game/modding` owns menu and command adapter. Shared-file changes are plugin wiring (`main.rs`, `app.rs`), one pause-menu row, a read-only grind observation method and the existing animation evaluator/parser's owner-scoped overrides. Other owners should retain these narrow hooks when merging. Baseline is local merge `26f056c`; no original checkout, private asset tree or other task configuration was modified.
+`sdk.trainer.apply(tuning)` installs one owner's reversible native tuning. Only one mod
+can own it at a time. Numeric fields default to 1 on each call; `hold_fakie` defaults false.
+Supported multipliers are pop, grind_pop, push_speed, push_power, braking, steering,
+offboard_jump, grip, turn_power and manual_drag (0.25..4), and wobble (0..2).
+`hold_fakie=true` suppresses the automatic stance switch. Unknown/nonfinite values fail.
+Disable/reload/fault restores defaults; native contact/state conditions still apply.
+These are parameter multipliers, not guarantees of measured speed or height.
 
-### Recorded non-game results
+`sdk/examples/native-trainer` demonstrates tuning, HUD text, checkpoints, timers,
+breadcrumbs, beacons and configurable shortcuts. Defaults: F5 save checkpoint, F6 return,
+F7 stopwatch, F8 clear transient data, F9 beacon. Its text data stays in the package.
+`sdk/examples/mario-kart` demonstrates vehicles, controller binds, driving HUD, fitted
+rider animations, steering, ramp collision tuning and engine audio. Proprietary assets
+are local-only. Both examples are packaged as ZIPs in top-level mods/ for this build.
 
-On 2026-09-08, all 13 original standalone SDK tests passed. The Windows release build and direct-output string/SHA-256 identity checks passed. The first release attempt diagnosed a stale shared `skate-core` artifact missing the merged respawn module; the helper now refreshes only this worktree's local crate source timestamps before compiling, preserving all dependency cache contents. Existing engine warnings remain. No interactive menu, native teleport or authored animation visual result is claimed.
-
-Private manual-test setup uses this task's own real asset-root directory with a read-only junction to the prepared `private` data, and its own settings directory. Maps are referenced through a junction. The launcher therefore does not use another task's writable settings root. None of these references, prepared assets, personal paths or binaries are tracked.
-
-## Native Trainer and pause-panel update
-
-The bundled Speedometer and Route Trainer examples have been removed. `mods/native-trainer` is the single bundled mod, disabled by default. Its seven settings control pop height, grind pop height, push speed, push power, braking, steering and wobble. All start at **1.00x stock**. Pop/grind pop/push speed/push power/braking/steering range from 0.25x to 4x; wobble ranges from 0x to 2x, in 0.25 increments. There is no direct board-velocity write, invincibility or global gravity cheat.
-
-The Mods list now has a right-aligned **ENABLED** badge in green or **DISABLED** in red; the selected mod has an explicit **ENABLE MOD / DISABLE MOD** action. A faulted mod is DISABLED with its error in the detail area. Whenever a mod is running, Escape shows its settings in a separate left-hand panel beside the normal pause controls. Click a value to increase/cycle it, or press **Tab / controller X** to focus that panel, then **Up/Down** to select and **Left/Right** to adjust. Tab/X returns focus to normal pause controls. Select the mod name to open its full enable/disable/settings page. Text settings open the full editor. Lists longer than ten rows page as selection advances.
-
-`sdk.trainer.apply(tuning: table) -> nil` queues an owner-scoped native tuning override. Optional fields `pop`, `grind_pop`, `push_speed`, `push_power`, `braking`, `steering`, `wobble` have the ranges above and default to 1 on **each call**. Unknown fields and nonfinite/out-of-range values raise errors. Only one mod can own trainer tuning at a time; another owner is rejected and stopped. Disabling, reloading or faulting the owner restores default multipliers. Active tuning survives map replacement and is reapplied before further simulation. Existing momentum and an already-launched jump are not rewound; subsequent physics calculations use current tuning.
-
-Source bindings: ground pop scales the current `GroundJumpMode` minimum/maximum heights before the existing ground-jump calculation. Grind pop scales the existing interpolated launch-height argument. Push speed scales the animation-provided push target plus `maximum_pushable_speed`; push power scales difficulty-specific `mode_speed_changes`. Brake strength scales the native foot/tail brake force and steering scales `general_scalar`. Wobble scales the existing mode amplitude multiplier. Ground profiles are derived anew from the stock selected difficulty/surface, so edits never compound and do not overwrite the customiser or installed data. Native floors, contact conditions, speed conservation and state transitions still apply: a 2x setting is a parameter multiplier, not a guaranteed 2x measured jump/speed.
-
-Trainer integration is compile-checked and the standalone Lua/schema suite covers command validation and setting delivery. Native gameplay effects, controller focus and two-panel layout still require the user-run launcher. No game was launched for this update.
-
-The trainer update passes 14 standalone Lua/schema tests and a static-CRT release build. Use **PLAY-NATIVE-TRAINER.bat** for this update; its executable and preferences are isolated from the previous SDK test build.
-
-## Draggable per-mod windows
-
-Use `PLAY-MOD-WINDOWS.bat` for the latest settings-window build (`Build-ModWindows.ps1`). The ordinary Escape menu stays in its original centered position. Each enabled mod receives its own compact window, initially at the left, with a title you can drag. The title-bar minus button collapses that window; plus expands it. Each setting has separate minus/plus controls to decrease/increase numbers (within the manifest bounds), cycle choices, or toggle booleans. String controls open the full editor. Values are still saved and delivered to Lua immediately.
-
-Positions and collapse state are retained for the current process, including closing Escape and disabling/re-enabling a mod; they are not saved across game restarts. Clicking a window brings it forward. Tab/controller X cycles focus through enabled mods and then back to the main pause controls; arrows select/adjust within the focused mod. Each window shows a continuous, clipped settings list. Use the mouse wheel over the window to scroll; keyboard/controller selection scrolls the selected setting into view. The value minus/plus buttons edit that row without changing the other rows. Manage mod opens that mod's enable/disable page. The main pause controls remain mouse-clickable when a mod has keyboard focus. Dragging prevents accidental main-menu mouse actions. No game was launched to validate this UI update; its interactive behavior remains for user testing.
-
-## Showcase 2.0 and top-level packages
-
-`PLAY-SHOWCASE.bat` / `Build-Showcase.ps1` provide the current showcase build.
-The build directory contains the executable and a real `mods/native-trainer`
-folder beside it. Only original Lua/JSON/text documentation is copied there.
-Existing edited mod files are preserved on rebuilding, with a diagnostic if they
-differ from bundled sources. The launcher relies on executable-relative discovery;
-it does not redirect mods to the checkout. `SKATE3_MODS` remains an explicit override.
-`mods/README.md` documents this layout for players; use Open mods folder in-game.
-
-Native Trainer 2.0 now has 23 declarative settings: eleven native multipliers plus
-HUD/units/label/help, breadcrumbs/spacing/colour and five keyboard shortcut choices.
-The four added `sdk.trainer.apply` fields are `offboard_jump`, `grip`, `turn_power`
-and `manual_drag` (all default 1, finite 0.25..4). Off-board jump scales the existing
-biped `JumpInput.height_792` before native launch preparation. Grip scales ground
-wheel static/dynamic friction and slide-friction strength. Turn power scales the
-heading controller's turn strength; manual drag scales its balance drag. No raw
-velocity, gravity, mass or state-controller replacement was added.
-
-The player snapshot now additionally includes `heading:number`, the animation-root
-yaw in radians (atan2 of forward X/Z), for source-backed checkpoint orientation.
-The expanded Lua example demonstrates this native teleport request with a separate
-trainer checkpoint; F5 saves and F6 returns by default. F7 starts/stops the active-play
-stopwatch, F8 clears transient session data/markers, and F9 places a visual beacon.
-All shortcuts are configurable choices. Saving is intended on valid clear ground;
-a blocked native return reports a mod error rather than bypassing engine gates.
-
-The HUD displays board speed/peak, approximate travel, position and observed bail/
-grind statistics. It is not the career scoring system or precise odometry. Optional
-breadcrumbs reuse 24 keys; beacons reuse eight; all visual objects have no collision.
-Timers remove temporary notices; settings update visuals immediately; map changes
-clear checkpoint, stopwatch, markers and statistics. Script reload resets transient
-Lua state while preserving compatible saved settings. `help.txt` demonstrates
-package-relative text loading. No private game assets are shipped.
-
-Standalone Lua tests exercise save/return command payloads, stopwatch creation,
-world-change cleanup, bounded trail keys and immediate HUD/tuning settings. Actual
-native gameplay effects and visuals remain user-run; no game process was launched.
-
-
-Trainer 2.1 adds `sdk.trainer.apply { hold_fakie = true }` (default false).
-It blocks the automatic idle/bump transitions into the native stance-switch animation; normal
-steering, slide overrides and trick inputs remain native. Turning the setting
-off, disabling the mod or retiring its owner restores stock behavior.
-
-Enabled-mod windows default to 360 by 760 pixels, bounded by the display.
-Drag the bottom-right `//` grip to resize (minimum 320 by 260); the settings
-viewport grows with the window and keeps mouse-wheel scrolling. Window sizes
-are retained in memory while the game runs, alongside position/collapse state.
-
-Each enabled-mod settings viewport also has a right-side scrollbar. Drag its thumb or click the track to jump; wheel and keyboard scrolling update the same thumb. It resizes with the window and dims when all settings fit.
-
-Vehicle SDK v1 adds Rapier vehicles and the Mario Kart example. See [vehicle-sdk.md](vehicle-sdk.md) for commands, animation hooks, limits and controls. Packages now allow 64 MiB for embedded models/animations.
+All owner-created visuals are removed on disable, reload or fault. Native skating and
+vehicle physics remain host-controlled; Lua does not receive memory pointers or World.