RUSTICDOCSSearch documentation

Scripting expansion audit and implementation status

This is an incremental implementation record, not a claim that the comprehensive expansion is complete. Baseline: engine 017db99b, docs 1a3fa6c.

Architecture and reuse audit

  • engine-world: private Bevy ECS, stable UUIDs and generational runtime refs; validated batched commands, deterministic hierarchy and transform propagation; versioned scene documents and additive instantiation. Reuse these for hierarchy, destruction, component queries, prefab/scene foundations; preserve scene format.
  • engine-core/gameplay: engine-owned easing, movement, tween, timers, sequences, paths, animation, IK, signal delivery and audio mixer. These are implemented; no replacement scheduler, timer, event bus, or easing implementation is needed.
  • engine-scripting: bundled Lua 5.4/QuickJS; external isolated C/C++, Python, .NET, Java, PHP and Luau hosts. All use GameplayHost.gameplay_query and generated SDKs; extend this single boundary. PHP/Web remain UI-scoped. Installed toolchains determine external adapter availability. Snapshot state differs from live queries.
  • engine-play: shared runtime world/context, fixed simulation, isolated scripts, snapshot asset reads and lifecycle cleanup. Physics is a custom primitive AABB solver (physics.rs), not Rapier/Jolt: advanced joints, ragdolls, vehicles, CCD, slopes and robust shape casts require a deliberate backend integration first.
  • engine-rhi, renderer-wgpu: typed generational GPU resources, renderer selection, mesh/primitive extraction, WGSL pipelines and environment/sky. Resource presence is not evidence of a script API or an advanced rendering effect. Do not advertise volumetrics, cloth or post-processing before rendering paths exist.
  • apps/runtime/game_ui.rs: static HTML text/CSS to SVG raster overlay. Embedded Web JavaScript runs separately in QuickJS. No browser DOM, forms, layout engine, input routing or reactive rendering bridge exists. Browser runtime integration is a prerequisite for Category F; state maps alone cannot implement that category.
  • engine-assets, engine-project, engine-platform: existing import workers, VFS/path validation, project storage, task/logging facilities and window plumbing. Script saves must use a per-game writable directory, not immutable play snapshots.
  • apps/editor, engine-editor: scene attachment/inspection and embedded isolated Play already share engine-world/runtime; no competing native UI framework needed.
  • docs: Markdown guide/API sources, generated API reference, docs-catalog.ts navigation and API example tests. Engine-local documentation mirrors relevant pages.
  • examples: currently contains only a license; add small runnable scripts with editor setup rather than fake project files or placeholders.

Constraints and verification

No new runtime dependencies are needed for entity foundations. Existing project serialization and public function names must stay compatible. Runtime-only tags, groups and lifetime deadlines must be documented as such. Hierarchy preservation must reject transforms that need shear rather than silently changing world poses. Linux can run Rust and available language tests; Windows installer qualification requires the repository Windows workflow. Hardware-dependent rendering remains unverified unless executed.

Feature-by-feature checklist

“Partial” records an existing engine substrate, not completion of the requested API. “Not started” means no implementation was found in the inspected runtime/API paths. The advanced physics and browser UI prerequisites above block those dependent features; other unchecked work remains independent and not started.

CategoryRequested capabilityStatus
Category ATags.add()Implemented: Rust/runtime/bindings/docs; executed validation below
Category ATags.remove()Implemented: Rust/runtime/bindings/docs; executed validation below
Category ATags.find_all()Implemented: Rust/runtime/bindings/docs; executed validation below
Category AGroups.create()Implemented: Rust/runtime/bindings/docs; executed validation below
Category AGroups.add()Implemented: Rust/runtime/bindings/docs; executed validation below
Category AGroups.get_members()Implemented: Rust/runtime/bindings/docs; executed validation below
Category AHierarchy.set_parent()Implemented: Rust/runtime/bindings/docs; executed validation below
Category AHierarchy.get_children()Implemented: Rust/runtime/bindings/docs; executed validation below
Category AHierarchy.detach()Implemented: Rust/runtime/bindings/docs; executed validation below
Category AEntity.destroy()Implemented: Rust/runtime/bindings/docs; executed validation below
Category AEntity.destroy_after()Implemented: Rust/runtime/bindings/docs; executed validation below
Category AEntity.is_valid()Implemented: Rust/runtime/bindings/docs; executed validation below
Category AComponents.has()Implemented: Rust/runtime/bindings/docs; executed validation below
Category AComponents.get_all()Implemented: Rust/runtime/bindings/docs; executed validation below
Category AComponents.find_in_children()Implemented: Rust/runtime/bindings/docs; executed validation below
Category AComponents.attach()Partial: existing substrate; requested binding/behavior missing
Category AComponents.detach()Partial: existing substrate; requested binding/behavior missing
Category AComponents.set_active()Partial: existing substrate; requested binding/behavior missing
Category APrefab.instantiate()Partial: existing substrate; requested binding/behavior missing
Category APrefab.override()Partial: existing substrate; requested binding/behavior missing
Category APrefab.reset()Partial: existing substrate; requested binding/behavior missing
Category AScene.load_additive()Partial: existing substrate; requested binding/behavior missing
Category AScene.unload_additive()Partial: existing substrate; requested binding/behavior missing
Category AScene.mark_persistent()Partial: existing substrate; requested binding/behavior missing
Category AScene.transfer_entity()Partial: existing substrate; requested binding/behavior missing
Category AGameState.set()Not started
Category AGameState.get()Not started
Category AGameState.observe()Not started
Category AWorld.find_by_tag()Implemented: Rust/runtime/bindings/docs; executed validation below
Category AWorld.find_in_radius()Implemented: Rust/runtime/bindings/docs; executed validation below
Category APool.register()Not started
Category APool.acquire()Not started
Category APool.release()Not started
Category AInteraction.register()Not started
Category AInteraction.use()Not started
Category AInteraction.can_use()Not started
Category ADamage.apply()Not started
Category ADamage.set_resistance()Not started
Category ADamage.on_death()Not started
Category AInventory.add_item()Not started
Category AInventory.remove_item()Not started
Category AInventory.transfer()Not started
Category AQuest.start()Not started
Category AQuest.complete_objective()Not started
Category AQuest.get_progress()Not started
Category ACheckpoint.activate()Not started
Category ACheckpoint.respawn()Not started
Category AAbility.activate()Not started
Category AAbility.set_cooldown()Not started
Category AAbility.can_activate()Not started
Category BRigidBody.set_mass()Partial: existing substrate; requested binding/behavior missing
Category BRigidBody.set_velocity()Partial: existing substrate; requested binding/behavior missing
Category BRigidBody.set_angular_velocity()Partial: existing substrate; requested binding/behavior missing
Category BGravity.set_global()Partial: existing substrate; requested binding/behavior missing
Category BGravity.set_for_body()Partial: existing substrate; requested binding/behavior missing
Category BGravity.enable()Partial: existing substrate; requested binding/behavior missing
Category BPhysicsMaterial.set_friction()Partial: existing substrate; requested binding/behavior missing
Category BPhysicsMaterial.set_restitution()Partial: existing substrate; requested binding/behavior missing
Category BCollisionLayer.set()Partial: existing substrate; requested binding/behavior missing
Category BCollisionLayer.ignore_pair()Partial: existing substrate; requested binding/behavior missing
Category Bon_collision_enter()Not started
Category Bon_collision_stay()Not started
Category Bon_collision_exit()Not started
Category BTrigger.on_enter()Not started
Category BTrigger.on_exit()Not started
Category BTrigger.get_overlaps()Not started
Category BJoint.create()Not started
Category BJoint.set_limits()Not started
Category BJoint.break()Not started
Category BCharacter.move()Not started
Category BCharacter.is_grounded()Not started
Category BCharacter.set_slope_limit()Not started
Category BVehicle.set_throttle()Not started
Category BVehicle.set_steering()Not started
Category BVehicle.set_brake()Not started
Category BBuoyancy.add_body()Not started
Category BBuoyancy.set_density()Not started
Category BRagdoll.enable()Not started
Category BRagdoll.disable()Not started
Category BRagdoll.blend_weight()Not started
Category BRigidBody.set_ccd_mode()Partial: existing substrate; requested binding/behavior missing
Category BPhysics.box_cast()Partial: existing substrate; requested binding/behavior missing
Category BPhysics.capsule_cast()Partial: existing substrate; requested binding/behavior missing
Category BPhysics.set_substeps()Partial: existing substrate; requested binding/behavior missing
Category BPhysics.get_step_stats()Partial: existing substrate; requested binding/behavior missing
Category BPhysics2D.set_axis_lock()Not started
Category BPhysics2D.set_gravity()Not started
Category CNavMesh.build()Not started
Category CNavMesh.find_path()Not started
Category CNavMesh.update()Not started
Category CNavAgent.set_destination()Not started
Category CNavAgent.stop()Not started
Category CNavAgent.has_arrived()Not started
Category CBehaviorTree.create()Not started
Category CBehaviorTree.run()Not started
Category CBehaviorTree.set_blackboard()Not started
Category CStateMachine.add_state()Not started
Category CStateMachine.transition()Not started
Category CStateMachine.get_state()Not started
Category CPerception.can_see()Not started
Category CPerception.can_hear()Not started
Category CPerception.get_targets()Not started
Category CAIMemory.remember()Not started
Category CAIMemory.recall()Not started
Category CAIMemory.forget()Not started
Category CPatrol.set_points()Not started
Category CPatrol.start()Not started
Category CPatrol.pause()Not started
Category CSteering.seek()Not started
Category CSteering.flee()Not started
Category CSteering.avoid()Not started
Category CFlock.create()Not started
Category CFlock.set_cohesion()Not started
Category CFlock.set_separation()Not started
Category CCover.find_nearest()Not started
Category CCover.reserve()Not started
Category CCover.release()Not started
Category CThreat.add()Not started
Category CThreat.get_highest()Not started
Category CThreat.clear()Not started
Category CSpawner.configure()Not started
Category CSpawner.set_limit()Not started
Category CSpawner.spawn_wave()Not started
Category CWorldStream.load_region()Not started
Category CWorldStream.unload_region()Not started
Category CWorldGen.generate_chunk()Not started
Category CWorldGen.set_seed()Not started
Category CBiome.get_at()Not started
Category CBiome.set_region()Not started
Category CBiome.get_properties()Not started
Category CWeather.set_rain()Not started
Category CWeather.set_wind()Not started
Category CWeather.set_snow()Not started
Category CDayNight.set_time()Not started
Category CDayNight.set_cycle_speed()Not started
Category CDestruction.fracture()Not started
Category CDestruction.apply_damage()Not started
Category DMaterial.set_texture()Partial: existing substrate; requested binding/behavior missing
Category DMaterial.set_parameter()Partial: existing substrate; requested binding/behavior missing
Category DShader.load()Not started
Category DShader.set_uniform()Not started
Category DShader.enable_keyword()Not started
Category DParticles.create()Not started
Category DParticles.emit()Not started
Category DParticles.set_rate()Not started
Category DPostFX.set_bloom()Not started
Category DPostFX.set_exposure()Not started
Category DPostFX.set_vignette()Not started
Category DLight.set_intensity()Partial: existing substrate; requested binding/behavior missing
Category DLight.set_range()Partial: existing substrate; requested binding/behavior missing
Category DLight.set_shadow_enabled()Partial: existing substrate; requested binding/behavior missing
Category DVolumetrics.set_density()Not started
Category DVolumetrics.set_scattering()Not started
Category DMesh.create()Not started
Category DMesh.set_vertices()Not started
Category DMesh.set_indices()Not started
Category DMeshDeform.set_vertex()Not started
Category DMeshDeform.apply()Not started
Category DTerrain.set_height()Not started
Category DTerrain.paint_layer()Not started
Category DTexture.create()Not started
Category DTexture.set_pixels()Not started
Category DTexture.generate_mipmaps()Not started
Category DRenderTarget.create()Partial: existing substrate; requested binding/behavior missing
Category DRenderTarget.capture_camera()Partial: existing substrate; requested binding/behavior missing
Category DDecal.spawn()Not started
Category DDecal.set_material()Not started
Category DCloth.set_wind()Not started
Category DCloth.set_stiffness()Not started
Category DInstancing.create_batch()Partial: existing substrate; requested binding/behavior missing
Category DInstancing.update_instances()Partial: existing substrate; requested binding/behavior missing
Category DLOD.set_distances()Partial: existing substrate; requested binding/behavior missing
Category DLOD.set_bias()Partial: existing substrate; requested binding/behavior missing
Category DOcclusion.set_enabled()Not started
Category DOcclusion.set_occluder()Not started
Category DRenderSettings.set_shadow_quality()Partial: existing substrate; requested binding/behavior missing
Category DRenderSettings.set_antialiasing()Partial: existing substrate; requested binding/behavior missing
Category DSprite.set_region()Partial: existing substrate; requested binding/behavior missing
Category DSprite.set_flip()Partial: existing substrate; requested binding/behavior missing
Category DSprite.set_sorting_order()Partial: existing substrate; requested binding/behavior missing
Category DTilemap.set_tile()Not started
Category DTilemap.fill_area()Not started
Category DTilemap.get_tile()Not started
Category ESaveGame.write()Not started
Category ESaveGame.read()Not started
Category ESaveGame.delete()Not started
Category EPreferences.set()Not started
Category EPreferences.get()Not started
Category EPreferences.reset()Not started
Category EInputMap.register()Partial: existing substrate; requested binding/behavior missing
Category EInputMap.rebind()Partial: existing substrate; requested binding/behavior missing
Category EInputMap.get_strength()Partial: existing substrate; requested binding/behavior missing
Category EInputContext.push()Not started
Category EInputContext.pop()Not started
Category EGamepad.get_axis()Not started
Category EGamepad.get_button()Not started
Category EGamepad.set_vibration()Not started
Category ETouch.get_points()Not started
Category ETouch.get_swipe()Not started
Category ETouch.get_pinch()Not started
Category EMouse.capture()Not started
Category EMouse.release()Not started
Category EMouse.get_delta()Not started
Category EAssets.load_async()Partial: existing substrate; requested binding/behavior missing
Category EAssets.release()Partial: existing substrate; requested binding/behavior missing
Category EAssets.get_status()Partial: existing substrate; requested binding/behavior missing
Category EAssetBundle.load()Not started
Category EAssetBundle.unload()Not started
Category ESerializer.encode()Partial: existing substrate; requested binding/behavior missing
Category ESerializer.decode()Partial: existing substrate; requested binding/behavior missing
Category ELocalization.translate()Not started
Category ELocalization.set_locale()Not started
Category ERandom.set_seed()Not started
Category ERandom.range()Not started
Category ERandom.weighted_choice()Not started
Category EDisplay.set_resolution()Partial: existing substrate; requested binding/behavior missing
Category EDisplay.set_fullscreen()Partial: existing substrate; requested binding/behavior missing
Category EProfiler.begin_sample()Partial: existing substrate; requested binding/behavior missing
Category EProfiler.end_sample()Partial: existing substrate; requested binding/behavior missing
Category EProfiler.get_results()Partial: existing substrate; requested binding/behavior missing
Category EMemory.get_usage()Partial: existing substrate; requested binding/behavior missing
Category EMemory.get_allocations()Partial: existing substrate; requested binding/behavior missing
Category EDebug.draw_line()Partial: existing substrate; requested binding/behavior missing
Category EDebug.draw_sphere()Partial: existing substrate; requested binding/behavior missing
Category EDebug.draw_box()Partial: existing substrate; requested binding/behavior missing
Category ECapture.screenshot()Partial: existing substrate; requested binding/behavior missing
Category ECapture.save_to_user_folder()Partial: existing substrate; requested binding/behavior missing
Category ETask.run_async()Not started
Category ETask.cancel()Not started
Category ETask.get_status()Not started
Category EPlatform.get_os()Not started
Category EPlatform.get_architecture()Not started
Category EPlatform.is_mobile()Not started
Category EAccessibility.get_preferences()Not started
Category EAccessibility.set_subtitles()Not started
Category FUI.open()Partial: existing substrate; requested binding/behavior missing
Category FUI.close()Partial: existing substrate; requested binding/behavior missing
Category FUI.is_open()Partial: existing substrate; requested binding/behavior missing
Category FUI.set_state()Partial: existing substrate; requested binding/behavior missing
Category FUI.get_state()Partial: existing substrate; requested binding/behavior missing
Category FUI.watch_state()Partial: existing substrate; requested binding/behavior missing
Category FUI.send()Partial: existing substrate; requested binding/behavior missing
Category FUI.on_message()Partial: existing substrate; requested binding/behavior missing
Category FUI.focus()Partial: existing substrate; requested binding/behavior missing
Category FUI.blur()Partial: existing substrate; requested binding/behavior missing
Category FUI.get_focused()Partial: existing substrate; requested binding/behavior missing
Category FUI.set_z_index()Partial: existing substrate; requested binding/behavior missing
Category FUI.bring_to_front()Partial: existing substrate; requested binding/behavior missing
Category FUI.open_modal()Partial: existing substrate; requested binding/behavior missing
Category FUI.close_modal()Partial: existing substrate; requested binding/behavior missing
Category FUI.capture_input()Partial: existing substrate; requested binding/behavior missing
Category FUI.release_input()Partial: existing substrate; requested binding/behavior missing
Category FUITheme.set()Not started
Category FUITheme.get()Not started
Category FUITheme.update_variable()Not started
Category FUI.translate()Partial: existing substrate; requested binding/behavior missing
Category FUI.set_locale()Partial: existing substrate; requested binding/behavior missing
Category FUI.set_viewport()Partial: existing substrate; requested binding/behavior missing
Category FUI.set_scale()Partial: existing substrate; requested binding/behavior missing
Category FWorldUI.attach()Not started
Category FWorldUI.set_size()Not started
Category FWorldUI.face_camera()Not started
Category FUI.world_to_screen()Partial: existing substrate; requested binding/behavior missing
Category FUI.screen_to_world()Partial: existing substrate; requested binding/behavior missing
Category FUI.notify()Partial: existing substrate; requested binding/behavior missing
Category FUI.dismiss_notification()Partial: existing substrate; requested binding/behavior missing
Category FUI.set_loading_progress()Partial: existing substrate; requested binding/behavior missing
Category FUI.set_loading_message()Partial: existing substrate; requested binding/behavior missing
Category FUI.set_screen_reader_label()Partial: existing substrate; requested binding/behavior missing
Category FUI.announce()Partial: existing substrate; requested binding/behavior missing
Category FUI.add_class()Partial: existing substrate; requested binding/behavior missing
Category FUI.remove_class()Partial: existing substrate; requested binding/behavior missing

Entity-foundations slice

17 shared runtime APIs now use the existing SceneWorld command/lifetime system. This is the first incremental slice of Phase 1; the rest of the comprehensive request remains unfinished. Dynamic attachment, prefabs/pooling, streaming, physics expansion, input devices, persistence, AI, rendering and browser UI are not implemented by this slice. Do not infer their support from this checklist.

Implementation choices: runtime-only metadata avoids a project schema change; subtree deletion uses validated batches; deadlines use generation-checked refs; world-preserving reparent rejects shear; component queries use existing schemas. C and C++ preserve their established error/ownership conventions. No dependencies were added. The next independent slice should finish component lifecycle and prefab/scene instance lifecycle before pooling; then wire fixed input and saves. Advanced physics needs a backend decision/integration, and interactive HTML needs an actual browser DOM runtime with a capability-limited gameplay bridge.

Validation is recorded here after execution. Missing toolchains and Windows installer/hardware qualification remain separate from API test results.

Executed validation (Linux)

  • cargo test -p engine-world -p engine-play -p engine-scripting --locked: 138 passed, 0 failures (31 world, 67 play, 40 scripting).
  • cargo check --workspace --all-targets --locked: passed, including editor/runtime.
  • Clippy for all targets of the three changed crates with -D warnings: passed.
  • cargo fmt --all --check and Git whitespace checks: passed.
  • Live foundation fixtures: Lua 5.4, Luau, JavaScript, HTML inline JavaScript, Python, C and C++ passed. Installed .NET SDK 10.0.401 in the workspace and reran the fixture: C# also passed. Java and PHP fixtures were skipped because those toolchains are unavailable. The CI adapter-conformance job runs the entity fixture with all toolchains installed and fails if any required adapter is missing. That job passed on engine commit efc834d8, including Java and PHP: all supported adapters are now verified in CI, with local execution coverage explicitly distinguished above.
  • Built the separate bundled Luau host and put it on PATH for the Rust tests. This also resolved the original audio-recording test's missing-host failure.
  • Both published Lua/Python example scripts executed in the real world adapter.
  • Docs: lint with zero warnings, static build, TypeScript check, moderate npm audit (0 vulnerabilities), 24 site tests on the updated docs main, API reference/example validation, snippet syntax, documentation structure and exported-link checks all passed. The example validator checks coverage/rendering (1600 existing/new snippets); it does not execute every documented snippet in every external toolchain.
  • Local Windows installer command failed: powershell is absent on this Linux host. Windows workflow qualification is attempted separately; no fresh installer or Windows/macOS hardware verification is claimed by these Linux results.

Changed files and deliverables

Engine implementation: crates/engine-world/src/foundations.rs, world.rs, lib.rs; crates/engine-play/src/entity_services.rs, script_runtime.rs, lib.rs. Bindings/editor hints: crates/engine-scripting/src/lua.rs, cpp_sdk.rs, workspace.rs, .github/workflows/quality.yml, and sdk/{gameplay.lua,gameplay.js,rustic.h,rustic.py,rustic.php, Rustic.cs,Rustic.java,entity-api.lua,entity-api.d.ts}. Engine docs: this checklist, Scripting/API/entity-foundations.md, Scripting/README.md. Tested examples: examples/entity-foundations/.

Docs repository: matching checklist/API/README Markdown, lib/api-reference.ts, lib/api-reference-markdown.ts, lib/api-example-data.json, lib/api-examples.ts, lib/docs-catalog.ts. Navigation adds a setup guide, status guide and 17 individual API pages. Signatures and language differences are listed in the entity foundations reference.

Examples repository: entity-foundations/{README.md,behavior.lua,behavior.py}. No cloud hosting, database, billing, infrastructure or other unrelated repo changed.

CI evidence: required all-adapter conformance and Windows qualification run. The adapter-conformance, dependency/license, secret-scan and workflow-syntax jobs passed. Windows installer qualification passed for engine commit efc834d8; the workflow produced and uploaded a fresh Engine/dist/RusticGameEngine-Setup-*.exe (its upload step fails if that file is absent). The artifact is windows-installer, created 2026-10-12 15:23:50 Pacific/Auckland, 21,661,942 bytes, ID 11723192155. Download the installer artifact. The full comprehensive expansion remains unfinished.

Review: engine #30, API documentation #31 (merged while work continued), validation update #33, examples #1.