diff --git a/content/user/scripting.md b/content/user/scripting.md index 03c902e..e8b1916 100644 --- a/content/user/scripting.md +++ b/content/user/scripting.md @@ -33,9 +33,9 @@ Lua and JavaScript also accept compatible snake-case spellings; canonical names | Runtime / operation | Execution behavior | | --- | --- | | Embedded Lua 5.4 core writes | Host methods update the Play world immediately, including translation, attributes and properties. `instance.add/clone` return the new stable ID immediately. | -| Embedded JavaScript / Web core writes | Translation, property/attribute writes, enabled state, camera selection, logging and instance creation are collected and applied in order after a successful callback. Reads use the callback snapshot; creation returns no new entity ID. | +| Embedded JavaScript / Web core writes | Translation, property/attribute writes, enabled state, camera selection, logging and instance creation are collected and applied in order after a successful callback. Reads use the callback snapshot; creation returns no new entity ID. A canonical scene-object API call can flush these commands before resolving its target. | | External SDKs: Python, C, C++, C#, Luau, Java, PHP | Core commands normally commit with the callback response. A synchronous query flushes earlier commands in order before evaluating the query. Simple snapshot getters still use lifecycle state, so flushing does not refresh that snapshot. | -| Synchronous gameplay queries | Evaluate when called. Examples include physics queries/impulses, environment updates and audio controls. Embedded JavaScript queries do not automatically flush earlier queued core writes. | +| Synchronous gameplay queries | Evaluate when called. Examples include physics queries/impulses, environment updates and audio controls. Embedded JavaScript queries normally do not flush earlier queued core writes. Canonical `game.scene.Scene.Object` target resolution flushes earlier commands before resolving the live path; this also applies to HTML inline JavaScript. | | Scheduled actions / events | Actions are registered and advanced by the shared scene clock. Events/completion callbacks are delivered through the scheduler, not by a direct call into another script’s VM. | These distinctions describe the current adapters, not a transaction guarantee. In particular a Lua write already applied before a later error is not automatically rolled back. Keep order-sensitive operations explicit and avoid assuming a later getter sees a deferred write. API 1.1 is the gameplay API capability version; it is unrelated to Docs v0.1. diff --git a/docs/Scripting/apiPaths.md b/docs/Scripting/apiPaths.md new file mode 100644 index 0000000..044e525 --- /dev/null +++ b/docs/Scripting/apiPaths.md @@ -0,0 +1,194 @@ +# Call APIs through scene and file paths + +All ten scripting types provide the same three roots. Choose the root from the +thing the call operates on: + +| Target | Root | Lua / Luau example | +| --- | --- | --- | +| An object in a named scene | `game.scene.SceneName.ObjectPath` | `game.scene.Demo.Room.Player:tween("Position", {8,0,0}, 2)` | +| A service that needs no scene object | `game.rustic` | `game.rustic:after(1, function() print("ready") end)` | +| A file in the Explorer | `game.rustic.files.ExplorerPath` | `game.rustic.files.assets.sounds["hit.wav"]:load()` | + +The scene path supplies the object argument. The file path supplies the source +file argument. Pass the remaining arguments in their usual order. Returned action +handles, voices, timers and builders keep their existing methods and lifecycle. +Old `Tween`, `Movement`, `Game.scene`, `rustic.game`, and other service calls remain +available for existing scripts. + +## Set up and run + +1. Open a scene whose document name is **Demo**. Create a root named **Room**, a + child named **Player**, and a separate root named **Controller**. Give siblings + unique names. Player's complete hierarchy path is `Room.Player`. +2. Select Controller. Use **Programming > Object Component Script**, choose Lua, + paste the example below, save, and attach it to Controller with + **Programming > Attach Existing Script** or **+ Add Component** in the Inspector. +3. Press **Play**. Player moves to local position `(8, 0, 0)` over two scene-clock + seconds. Controller retains its position. After one scene-clock second the log + shows `ready`. Stop Play to return to the authored scene. + +```lua +return {Start=function() + game.scene.Demo.Room.Player:tween("Position", {8,0,0}, 2, "OutCubic") + game.rustic:after(1, function() print("ready") end) +end} +``` + +Global and Scene startup scripts can also use named paths; the target does not +have to own the script. Calls resolve the live loaded scene, including edits +queued earlier in the same callback. A path retained in a variable remains a +path: after renaming or reparenting its target, use the new hierarchy path. +An unloaded scene, missing object, or duplicate full hierarchy path is rejected +rather than selecting a different object. Only the currently loaded scene is +addressable. + +## Native syntax in every language + +These snippets go inside your existing `Start` / `on_start` callback. Each starts +the same Player tween. See [Scopes, lifecycle and execution](/docs/guides/scripting) +for creating and attaching scripts in each language. + +| Language | Scene object call | +| --- | --- | +| Lua 5.4 / Luau | `game.scene.Demo.Room.Player:tween("Position", {8,0,0}, 2)` | +| JavaScript / HTML inline JS | `game.scene.Demo.Room.Player.tween("Position", [8,0,0], 2);` | +| Python | `game.scene.Demo.Room.Player.tween("Position", [8,0,0], 2)` (import `game` from `rustic`) | +| C# | `game.scene["Demo"]["Room"]["Player"].tween("Position", new double[]{8,0,0}, 2);` (use `using static Rustic;`) | +| C++ | `game.scene["Demo"]["Room"]["Player"].tween("Position", RusticValue::Array{8,0,0}, 2.0);` | +| Java | `game.scene.scene("Demo").object("Room.Player").tween("Position", new double[]{8,0,0}, 2);` (inside a `Rustic` subclass) | +| PHP | `$game->scene->Demo->Room->Player->tween("Position", [8,0,0], 2);` (declare `global $game;` in callbacks) | + +C has no implicit receiver or arbitrary named members. Select a path value and +pass it explicitly as `self`; the selected value supplies the target: + +```c +RusticScenePath player = game.scene("Demo", "Room.Player"); +player.tween(player, "Position", + (RusticValue){.type=RUSTIC_VECTOR,.vector={8,0,0},.length=3}, + 2, "Linear", NULL); +``` + +Use subscripts for names with spaces and filenames with extensions in Lua, +Luau, JavaScript, Python, C# and C++. For example, +`game.scene["Demo Scene"]["Room"]["Player One"]`. +Java accepts the scene and complete object path as strings. PHP accepts a +property such as `$game->scene->{"Demo Scene"}->Room->{"Player One"}`. + +## Object methods + +Short names cover common calls. Family-prefixed names distinguish APIs whose +original names overlap. Both forms bind the receiver to the target: + +| Family | Methods on `game.scene.Scene.ObjectPath` | +| --- | --- | +| Attributes | `EditAttribute`, `edit_attribute` (`GetAttribute` / `get_attribute` in embedded Lua) | +| Tween | `tween` / `tweenTo`, `tweenMove`, `tweenRotate`, `tweenScale`; action/options variants where already supported | +| Movement | `moveTo`, `move`, `rotateTo`, `lookAt`, `follow`, `orbit`; also `movementMoveTo`, `movementMove`, `movementRotateTo`, `movementLookAt`, `movementFollow`, `movementOrbit` | +| Paths | `followPath` / `pathFollow`, `pathFollowSpeed` where already supported | +| Effects | `fade`, `flash`, `shake`, `pulse`; also the `effects` prefix, such as `effectsFade` | +| Camera | `setCurrentCamera()`, `cameraMoveTo`, `cameraZoom`, `cameraFov`, `cameraFollow`, `cameraOrbit`, `cameraLookAt`, `cameraShake`, `cameraTransition` | +| Physics | `impulse`, `force`, `launch`, `knockback`; also the `physics` prefix | +| Animation | `playAnimation` / `animationPlay`, `animationRegister`, `animationClips`, `animationBlend`, `animationTransition`, `animationAddMarker`, `animationIk`, `animationFootPlacement`, `animationLookAt`, `animationHeadTracking`, `animationRecoil`; registration/action variants where already supported | +| Events | `eventsConnect(name, callback)`, `emit(name, arguments)` | +| Tags and groups | `addTag` / `tagsAdd`, `removeTag` / `tagsRemove`, `groupsAdd(groupName)` | +| Hierarchy | `setParent` / `hierarchySetParent`, `getChildren` / `hierarchyGetChildren`, `detach` / `hierarchyDetach` | +| Instances | `clone(parent)`, `add(parent)` | +| Lifetime | `destroy` / `entityDestroy`, `destroyAfter` / `entityDestroyAfter`, `isValid` / `entityIsValid` | +| Components | `hasComponent` / `componentsHas`, `getComponents` / `componentsGetAll`, `findInChildren` / `componentsFindInChildren` | + +Arguments and backend limits are those of the existing API in your language, +minus the receiver argument. For example, `groupsAdd` binds the **second** original +argument; pass only the group name. In languages whose follow/hierarchy APIs take +string targets, pass another canonical scene path string, such as +`"game.scene.Demo.Room.Leader"`. Lua, JavaScript, Python and PHP also accept scene +path objects as these arguments. + +## Global methods + +Call timers with `game.rustic:after(...)` or `:every(...)` in Lua/Luau, and native +member calls in other languages. Interpolation uses `lerp`, `slerp`, +`inverseLerp`, `remap`, and `smoothDamp`. World physics queries use `raycast`, +`sphereCast`, `overlap`, and `explosion`. Clock operations use `timeScale`, +`pause`, and `resume`; camera selection can use the scene object’s `setCurrentCamera()` method +(or the global `setCurrentCamera(path)` convenience); `currentCamera()` reads +the current camera where supported. Scene lighting uses `getEnvironment()` and +`setEnvironment(settings)`. + +Builders use `sequence()` and `timeline()`, and curves use `createPath(...)`. +Value animation uses `tweenValue(...)` / `animationValue(...)`. Global signals use +`on`, `once`, `emit`, and `disconnect`. Audio device enumeration/selection keeps +its snake case names; voice operations use `audioVolume`, `audioPitch`, +`audioFadeIn`, `audioFadeOut`, and `audioCrossfade`. Tag/group/world searches use +`tagsFindAll`, `groupsCreate`, `groupsGetMembers`, `worldFindByTag`, and +`worldFindInRadius`. + +Family-prefixed equivalents are available, such as `timerAfter`, `smoothLerp`, +`clockPause`, `physicsRaycast`, and `sequenceNew`. The existing owner API is also +reachable under `game.rustic`, including `entity_id`, `delta_time`, `input`, +`key`, `get_property`, and `log`. These owner calls keep their existing scope. +No adapter gains an API its previous SDK did not implement. + +## Explorer file methods + +The Explorer path begins at the project root; include `assets` where applicable. +Each selected child adds one `/` to the source path. An extension stays in a +single filename segment: `["hit.wav"]`, not `.hit.wav`. + +For Lua/Luau audio, import a WAV, MP3, OGG, FLAC or AAC file as +`assets/sounds/hit.wav` (use its actual extension) and ensure it appears in the Play +snapshot. Load the selected file before playback: + +```lua +local sound = game.rustic.files.assets.sounds["hit.wav"] +sound:load() +local voice = sound:play({volume=0.5}) +-- Later, release the decoded clip: +sound:Unload() +``` + +Separate expressions selecting the same Lua/Luau file retain its load state. +`:play()` before `:load()` reports an error. Other language SDKs keep their +existing direct playback model, for example: + +```javascript +game.rustic.files.assets.sounds["hit.wav"].play({volume: 0.5}); +``` + +```python +game.rustic.files.assets.sounds["hit.wav"].play(volume=0.5) +``` + +```cpp +game.rustic.files["assets"]["sounds"]["hit.wav"].play(0.5); +``` + +C# uses the same subscripts and `.play(...)`. Java uses +`game.rustic.files.object("assets/sounds/hit.wav").play(0.5, 1, false)`. +PHP uses `$game->rustic->files->assets->sounds->{"hit.wav"}->play(...)`. +C selects `RusticFilePath sound=game.rustic.files("assets/sounds/hit.wav")` and +calls `sound.play(sound, &options)`. + +Other file operations are `playAt` / `audioPlayAt`, `loadAnimation(object)`, +`add(parent)`, `clone(parent)`, and `setSkyTexture()`, using each language's +existing optional arguments. Loading animation binds the file's source argument +and still requires the scene entity argument. In Lua/Luau, file recordings use +`game.rustic.files["capture.wav"]:startRecording(options)`; recording without a +file and microphone capture use `game.rustic:startRecording()` and +`game.rustic:startHotMic()`. + +File paths retain the backend's validation. Missing assets, paths outside the +snapshot and unsupported file types fail with the existing diagnostics. + +## Troubleshooting + +- **Scene not loaded:** use the document name of the scene currently in Play. +- **Object missing:** include every parent, check exact spelling, and use the new + path after renaming or reparenting. Creating a path value does not validate it; + calling a method resolves it. +- **Ambiguous object:** rename siblings so the complete hierarchy path is unique. +- **Lua argument errors:** use `:` on the canonical roots and scene/file objects. +- **File missing:** select each directory separately and keep the extension in + one segment. Verify that the asset is included in the Play snapshot. +- **API unavailable:** check the original API's language support and signature in + [Use gameplay actions](/docs/guides/gameplay-actions). The path facade preserves + those capabilities and arguments. diff --git a/docs/Scripting/gameplayActions.md b/docs/Scripting/gameplayActions.md index 5068ea2..a4efbad 100644 --- a/docs/Scripting/gameplayActions.md +++ b/docs/Scripting/gameplayActions.md @@ -1,5 +1,9 @@ # Shared gameplay actions (API 1.1) +Use the [canonical API paths](/docs/guides/api-paths) to call object APIs on +`game.scene.SceneName.ObjectPath`, global APIs on `game.rustic`, and file APIs +on `game.rustic.files.ExplorerPath`. Existing calls below remain supported. + The engine now owns an action scheduler shared by scripting languages. Easing, interpolation, path traversal, composition, and lifetime cleanup run in Rust. The script only starts an action and handles its callbacks. You do not edit JSON or diff --git a/docs/Scripting/sceneObjects.md b/docs/Scripting/sceneObjects.md index 6350f6c..e368d5b 100644 --- a/docs/Scripting/sceneObjects.md +++ b/docs/Scripting/sceneObjects.md @@ -1,5 +1,9 @@ # Edit another scene object +Use the [canonical API paths](/docs/guides/api-paths) to call object APIs on +`game.scene.SceneName.ObjectPath`, global APIs on `game.rustic`, and file APIs +on `game.rustic.files.ExplorerPath`. Existing calls below remain supported. + Use a named scene and the object's full hierarchy path to change its built-in properties from a script attached elsewhere. For example: diff --git a/lib/api-docs.ts b/lib/api-docs.ts index 9b64538..9d0d1e8 100644 --- a/lib/api-docs.ts +++ b/lib/api-docs.ts @@ -9,7 +9,7 @@ const docs: Record = { gameplay: { title: "Shared gameplay actions (API 1.1)", summary: "Shared easing, tweens, movement, clip and procedural animation, timelines, timers, paths, cameras, physics, effects, audio and signals in all ten script types.", when: "Start an action during Start or an event callback. The scene advances it once per frame, even if the behavior has no Update function. Follow [Use gameplay actions](/docs/guides/gameplay-actions) for attachment, complete signatures and backend limits.", - calls: ["Tween.to / move / rotate / scale / value", "Movement.move / moveTo / rotateTo / lookAt / follow / orbit", "Animation.play / blend / transition / register / addMarker / value / ik", "Sequence / Timeline: move / to / wait / call / animation / parallel / play", "Timer.after / every", "Smooth / Interpolation: lerp / slerp / inverseLerp / remap / smoothDamp", "Path.create / follow", "Camera.moveTo / zoom / lookAt / follow / orbit / shake / transition", "Physics.raycast / sphereCast / overlap / force / impulse / explosion / knockback / launch", "Effects.fade / flash / shake / pulse", "Audio.get_output_devices / get_input_devices / set_output_device / set_input_device / load (Lua/Luau) / play / playAt / fadeIn / fadeOut / crossfade / volume / pitch", "rustic.game:startRecording / stopRecording / startHotMic / stopHotMic (Lua/Luau)", "Events.on / once / emit / connect / disconnect", "Clock.timeScale / pause / resume", "handle.state / pause / resume / cancel / reverse / onFinished"], + calls: ["game.scene.Scene.Object:tween / moveTo / playAnimation (native member syntax outside Lua/Luau)", "game.rustic:after / lerp / pause", "game.rustic.files.ExplorerPath:play / loadAnimation / add / setSkyTexture", "Tween.to / move / rotate / scale / value", "Movement.move / moveTo / rotateTo / lookAt / follow / orbit", "Animation.play / blend / transition / register / addMarker / value / ik", "Sequence / Timeline: move / to / wait / call / animation / parallel / play", "Timer.after / every", "Smooth / Interpolation: lerp / slerp / inverseLerp / remap / smoothDamp", "Path.create / follow", "Camera.moveTo / zoom / lookAt / follow / orbit / shake / transition", "Physics.raycast / sphereCast / overlap / force / impulse / explosion / knockback / launch", "Effects.fade / flash / shake / pulse", "Audio.get_output_devices / get_input_devices / set_output_device / set_input_device / load (Lua/Luau) / play / playAt / fadeIn / fadeOut / crossfade / volume / pitch", "rustic.game:startRecording / stopRecording / startHotMic / stopHotMic (Lua/Luau)", "Events.on / once / emit / connect / disconnect", "Clock.timeScale / pause / resume", "handle.state / pause / resume / cancel / reverse / onFinished"], parameters: [p("entity", "stable entity ID / resolved path", true, "Transform target; use an anchored Part to avoid competing gravity."), p("duration", "finite non-negative seconds", true, "Time to completion. Movement and tween helpers also provide duration or speed options."), p("easing", "Ease identifier", false, "Linear by default; all 31 shared curves are available.")], returns: "An operation handle. Completion is queued during Update. Cancellation and destroyed targets do not invoke completion.", examples: { @@ -24,7 +24,7 @@ const docs: Record = { PHP: "// Inside an on_start function with global $rustic:\nTween::move($rustic->entity_id(),[10,0,0],2,Ease::OutCubic);", "HTML / inline JS": "globalThis.behavior={Start(){\n Tween.move(rustic.entity_id(),[10,0,0],2,Ease.OutCubic);\n}};", }, - notes: ["Targets use local Position, Scale/Size, quaternion Rotation, Color, Opacity, perspective Fov in radians, or voice Volume/Pitch. Value callbacks animate script or UI state.", "Imported glTF/GLB/FBX clips retain source timing, inverse binds and skin weights. Physics uses primitive world AABBs and unit mass. Windows has device audio output; other platforms mix headlessly. See the guide for full signatures and backend limits.", "Operations and subscriptions clean up with their owner, scene, or reload. Failed reload retains previous operations. Callback exceptions disable the owner."] + notes: ["Use the [canonical API paths](/docs/guides/api-paths) in all ten script types: scene receivers supply the target object, global calls use game.rustic, and file receivers supply the Explorer source. Existing table APIs remain compatible.", "Targets use local Position, Scale/Size, quaternion Rotation, Color, Opacity, perspective Fov in radians, or voice Volume/Pitch. Value callbacks animate script or UI state.", "Imported glTF/GLB/FBX clips retain source timing, inverse binds and skin weights. Physics uses primitive world AABBs and unit mass. Windows has device audio output; other platforms mix headlessly. See the guide for full signatures and backend limits.", "Operations and subscriptions clean up with their owner, scene, or reload. Failed reload retains previous operations. Callback exceptions disable the owner."] }, entity: { title: "Entity & time API", summary: "Identify the behavior owner and read engine-supplied frame intervals.", @@ -49,7 +49,7 @@ const docs: Record = { when: "Read before applying relative movement. Write from `Update` for presentation movement or `FixedUpdate` for simulation movement. Do not rewrite an unchanged position every frame.", calls: ["rustic.get_translation()", "rustic.set_translation(x, y, z)"], parameters: [p("x", "finite number", true, "Local X relative to the parent."), p("y", "finite number", true, "Local Y relative to the parent."), p("z", "finite number", true, "Local Z relative to the parent.")], - returns: "Get returns three numbers. Set returns no entity value. Lua applies the host write immediately; JavaScript/Web defer it until callback completion; external SDKs commit at the response or a synchronous query flush. See [execution behavior](/docs/guides/scripting#when-mutations-take-effect).", + returns: "Get returns three numbers. Set returns no entity value. Lua applies the host write immediately; JavaScript/Web defer it until callback completion or a subsequent canonical scene-target resolution; external SDKs commit at the response or a synchronous query flush. See [execution behavior](/docs/guides/scripting#when-mutations-take-effect).", examples: { "Lua 5.4": "local x, y, z = rustic.get_translation()\nrustic.set_translation(x + 1, y, z)", JavaScript: "const [x, y, z] = rustic.get_translation();\nrustic.set_translation(x + 1, y, z);", @@ -85,7 +85,7 @@ const docs: Record = { attributes: { title: "Built-in attribute API", summary: "Read or edit engine-owned attributes on the behavior entity or a named scene object.", when: "Use attributes for built-in entity state. Prefer `set_translation` for Position and `set_enabled` for Enabled when those dedicated calls better express intent.", - calls: ["rustic.get_attribute(name)", "rustic.edit_attribute(name, value)", "rustic.game.Scene.Root.Child.EditAttribute(name, value)", "rustic.edit_object_attribute(source, name, value) — embedded Lua / JavaScript", "rustic.game.Scene.Root.Child:GetAttribute(name) — embedded Lua only"], + calls: ["game.scene.Scene.Root.Child:EditAttribute(name, value) — native member syntax outside Lua/Luau", "rustic.get_attribute(name)", "rustic.edit_attribute(name, value)", "rustic.game.Scene.Root.Child.EditAttribute(name, value)", "rustic.edit_object_attribute(source, name, value) — embedded Lua / JavaScript", "rustic.game.Scene.Root.Child:GetAttribute(name) — embedded Lua only"], parameters: [p("name", "string", true, "Name, Position, Size, Color (RGB), CanTouch, CanCollide, Anchored, or Parent."), p("value", "attribute-specific", true, "Value matching the attribute type.")], returns: "Get returns the current value. Edit validates a typed mutation; [write timing depends on the runtime](/docs/guides/scripting#when-mutations-take-effect).", examples: { @@ -178,7 +178,7 @@ const docs: Record = { title: "Current camera API", summary: "Select the camera used for the next game render.", when: "Call when gameplay changes viewpoints—vehicles, players, cutscenes, or returning to the main camera. Do not call every frame when unchanged.", calls: ["Game.setCurrentCamera(source)"], parameters: [p("source", "string or camera reference", true, "Stable camera entity ID or scene path.")], - returns: "No camera object. Lua selects immediately in the Play world; JavaScript/Web defer the selection until callback completion. External SDK commands commit at callback completion or query flush. Rendering observes the resulting active camera.", + returns: "No camera object. Lua selects immediately in the Play world; JavaScript/Web defer the selection until callback completion or a subsequent canonical scene-target resolution. External SDK commands commit at callback completion or query flush. Rendering observes the resulting active camera.", examples: simpleMutationExamples("Game.setCurrentCamera('Game.scene.Room.Camera')", "Game.setCurrentCamera(\"Game.scene.Room.Camera\");"), notes: ["The target must resolve to a camera in the play snapshot.", protocolNote], }, @@ -250,7 +250,7 @@ export function buildApiMarkdown(id: string) { } function codeLanguage(lang: string) { return ({ "Lua 5.4": "lua", JavaScript: "javascript", Python: "python", "C++": "cpp", "C#": "csharp", Luau: "lua", C: "c", Java: "java", PHP: "php", "HTML / inline JS": "javascript" } as Record)[lang]; } -function overview() { return `# Rustic scripting API\n\nThe reference is organized by what game code needs to do. Core operation pages include purpose, timing, variables, return behavior, and equivalent calls for all ten supported script types. The Gameplay APIs navigation section provides dedicated references for actions, easing, animation, composition, physics, audio, events and the scene clock. API 1.1 gameplay actions have an explicit language support matrix in [Use gameplay actions](/docs/guides/gameplay-actions).\n\n## Execution model\n\nGlobal scripts run before Scene scripts, then Object Component scripts. Mutation timing depends on the adapter: Lua host writes are immediate; JavaScript/Web core writes are deferred; external SDK queries may flush pending commands. Read [Scopes, lifecycle and execution](/docs/guides/scripting#when-mutations-take-effect) for the exact distinctions. Every gameplay language calls built-in functions. Lua, JavaScript, and Web use embedded bindings; external languages use engine-supplied SDKs with private transport.\n\n## Language support\n\n| Languages | Integration |\n| --- | --- |\n| Lua 5.4, JavaScript, HTML / inline JS | bundled embedded API |\n| Python, C#, C++, Luau, C, Java, PHP | engine-owned SDK and persistent external session |\n\n## Safety limits\n\nSource and responses are limited to 1 MiB. External callbacks have a three-second deadline. Boundary values are booleans, integers, finite numbers, strings, vectors, and optional stable entity IDs.`; } +function overview() { return `# Rustic scripting API\n\nThe reference is organized by what game code needs to do. Core operation pages include purpose, timing, variables, return behavior, and equivalent calls for all ten supported script types. The Gameplay APIs navigation section provides dedicated references for actions, easing, animation, composition, physics, audio, events and the scene clock. API 1.1 gameplay actions have an explicit language support matrix in [Use gameplay actions](/docs/guides/gameplay-actions).\n\n## Execution model\n\nGlobal scripts run before Scene scripts, then Object Component scripts. Mutation timing depends on the adapter: Lua host writes are immediate; JavaScript/Web core writes are deferred; canonical scene-target resolution and external SDK queries flush earlier commands. Read [Scopes, lifecycle and execution](/docs/guides/scripting#when-mutations-take-effect) for the exact distinctions. Every gameplay language calls built-in functions. Lua, JavaScript, and Web use embedded bindings; external languages use engine-supplied SDKs with private transport.\n\n## Language support\n\n| Languages | Integration |\n| --- | --- |\n| Lua 5.4, JavaScript, HTML / inline JS | bundled embedded API |\n| Python, C#, C++, Luau, C, Java, PHP | engine-owned SDK and persistent external session |\n\n## Safety limits\n\nSource and responses are limited to 1 MiB. External callbacks have a three-second deadline. Boundary values are booleans, integers, finite numbers, strings, vectors, and optional stable entity IDs.`; } function callbacks() { const names = ["OnCreate", "Start", "OnEnable", "FixedUpdate", "Update", "OnDisable", "OnDestroy", "OnStop"]; const nativeNames = ["on_create", "on_start", "on_enable", "fixed_update", "update", "on_disable", "on_destroy", "on_stop"]; diff --git a/lib/docs-catalog.ts b/lib/docs-catalog.ts index 138b9a4..56fa936 100644 --- a/lib/docs-catalog.ts +++ b/lib/docs-catalog.ts @@ -82,6 +82,7 @@ const categoryGroups: DocGroup[] = [ { slug: "api/operation-handles", title: "Operation handles", description: "Inspect, pause, resume, cancel and observe engine-scheduled actions.", source: "docs/Scripting/API/operation-handles.md" }, ] }, { label: "Scene API", docs: [ + { slug: "guides/api-paths", title: "Call APIs through paths", description: "Use scene object, global service and Explorer file API paths in every scripting language.", source: "docs/Scripting/apiPaths.md" }, { slug: "guides/scene-objects", title: "Edit scene objects", description: "Target an object by scene name and hierarchy in any script language.", source: "docs/Scripting/sceneObjects.md" }, { slug: "api/environment", title: "Scene environment", description: "Read and change sky textures, ambient and sun lighting, and haze from every script language.", source: "api:environment" }, { slug: "api/scene", title: "Scene lookup", description: "Find entities and enumerate stable scene paths.", source: "api:scene" },