{ "api_version": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "build_marker": "phase19-player-interface", "guides": [ { "example": "function compose_resource_counts()\n local result = world.query(\"world.resource.counts\", {page_size = 16})\n assert(result.status == \"completed\", result.detail)\n ui.begin_panel({\n id = \"addon.resource-counts\",\n title = \"Resources\",\n anchor = \"bottom-left\",\n x = 24, y = 24, width = 280, height = 180,\n movable = true,\n semantic_label = \"Current settlement resources\",\n semantic_role = \"status\"\n })\n for _, record in ipairs(result.records) do\n ui.row(record.key, tostring(record.total))\n end\n ui.end_panel()\nend", "id": "guide.create-panel", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "notes": [ "Panel IDs are package-scoped durable presentation identities. The host rejects duplicates inside one package and qualifies backend window state by package, so separate packages may reuse a local ID safely.", "Do not derive panel IDs from pointer values or transient record order; changing an ID intentionally creates a different presentation identity.", "A failed reload keeps the last valid composition graph active and records an error.package-reload diagnostic.", "Detached records may be retained as display values, but they do not grant authority over their source owners." ], "related": [ "ui.begin-panel", "ui.end-panel", "ui.row", "ui.surface.player-hud", "ui.slot.player-hud.panels", "world.query" ], "steps": [ "Add an extend contribution targeting ui.surface.player-hud/panels to the package manifest.", "Implement the declared callback and request only the bounded detached records it needs through world.query.", "Open one panel with a package-stable ID, anchored inset geometry, movable enabled, and explicit semantic label and role.", "Append rows, progress indicators, text, and tooltips, then balance the block with ui.end_panel.", "Validate the package, reload at a frame boundary, and inspect package diagnostics if the prior graph remains active." ], "summary": "Declare a panel contribution, query detached data, and compose a semantic movable panel without owning gameplay state.", "title": "Create a movable information panel", "url": "/api/v1/guides/guide.create-panel.html" }, { "example": "function compose_toolbar()\n ui.begin_panel({\n id = \"addon.toolbar\", title = \"Tools\",\n anchor = \"top-left\", x = 350, y = 24,\n width = 260, height = 115, movable = true,\n semantic_label = \"Addon tools\", semantic_role = \"toolbar\"\n })\n ui.button(\"Restore Standard\", \"ui.action.composition-proof.use-standard\",\n \"Restore the standard player interface\", 1)\n ui.end_panel()\nend", "id": "guide.extend-toolbar", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "notes": [ "An action is presentation intent until its handler submits a registered command or selects a provider.", "Duplicate action IDs or focus orders are rejected instead of being resolved by load order.", "Toolbar extensions cannot replace or hide the compiled recovery surface." ], "related": [ "ui.button", "ui.action", "lifecycle.handle-action", "ui.slot.player-hud.toolbar" ], "steps": [ "Declare an extend contribution targeting ui.surface.player-hud/toolbar.", "Register every logical action ID in the runtime catalog before a widget references it.", "Compose buttons with visible labels, semantic labels, and unique focus order values.", "Handle each action in the manifest-declared lifecycle action callback.", "Reload and verify keyboard traversal and action diagnostics." ], "summary": "Add deterministic logical actions to the standard toolbar without replacing its provider.", "title": "Extend the player toolbar", "url": "/api/v1/guides/guide.extend-toolbar.html" }, { "example": "function handle_action(action_id)\n if action_id == \"ui.action.composition-proof.use-alternate\" then\n ui.select_provider(\n \"ui.surface.player-hud\",\n \"worldforge.composition-proof.player-hud\"\n )\n elseif action_id == \"ui.action.composition-proof.use-standard\" then\n ui.select_provider(\n \"ui.surface.player-hud\",\n \"worldforge.standard.player-hud\"\n )\n end\nend", "id": "guide.replace-interface", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "notes": [ "Provider selection changes presentation composition only.", "The recovery shell remains compiled, non-replaceable, and available when all packages are disabled.", "If replacement validation fails, the host retains the prior valid provider graph." ], "related": [ "ui.select-provider", "ui.surface.player-hud", "ui.surface.recovery", "error.ui-composition-conflict" ], "steps": [ "Declare a provider for ui.surface.player-hud and a replace contribution that names the same provider.", "Compose the complete alternate surface through its callback using registered widgets and queries.", "Select the provider through ui.select-provider from a registered logical action.", "Provide a visible action that selects worldforge.standard.player-hud again.", "Test Safe Mode and standard restoration before treating the replacement as usable." ], "summary": "Provide an alternate player HUD while retaining the compiled recovery shell and explicit restoration path.", "title": "Replace the standard player interface", "url": "/api/v1/guides/guide.replace-interface.html" }, { "example": "ui.set_theme({\n id = \"worldforge.standard\",\n text_scale = 1.0,\n high_contrast = false,\n reduced_motion = true\n})", "id": "guide.theme-interface", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "notes": [ "Theme contracts affect presentation only and cannot alter engine or gameplay values.", "Text scaling and reduced-motion metadata must remain usable when a surface is replaced.", "A package should not infer concrete colors from semantic token names." ], "related": [ "ui.set-theme", "ui.theme.color", "error.invalid-theme" ], "steps": [ "Choose a stable theme ID owned by the package or first-party interface.", "Set bounded text scale, high-contrast preference, and reduced-motion preference.", "Use registered semantic color roles for meaning rather than hardcoded renderer colors.", "Compose all controls after applying the theme for the current contribution.", "Handle error.invalid-theme by retaining the prior valid graph and correcting the contract." ], "summary": "Request a validated theme contract and rely on semantic tokens instead of renderer-specific colors.", "title": "Apply semantic interface styling", "url": "/api/v1/guides/guide.theme-interface.html" }, { "example": "local receipt = command.submit(\n \"command.actor.take-control\",\n {\n actor_id = actor.actor_id,\n expected_actor_revision = actor.revision,\n expected_authority_revision = actor.authority_revision\n },\n 1\n)\nlocal completion_subscription = events.listen(\n \"events.command.completed\",\n function(event)\n feedback = event.payload.command_id .. \" completed\"\n end\n)", "id": "guide.normal-command", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "notes": [ "Commands request behavior; the authoritative owner performs the behavior once at a fixed tick.", "Expected revisions prevent stale interface state from overwriting newer simulation state.", "Post-commit events report facts and are not a second mutation path." ], "related": [ "command.submit", "command.receipt", "events.listen", "events.ignore", "events.after", "events.command.completed", "command.actor.take-control" ], "steps": [ "Query current owner revisions and stable target IDs immediately before submission.", "Submit the registered command ID and typed arguments through command.submit.", "Treat the accepted receipt as queued intent, not completed mutation.", "Subscribe to events.command.completed during initialization and treat its detached payload as post-commit evidence; edits affect only that callback-local copy.", "Handle validation, queue, budget, and owner rejection IDs without retry loops inside one callback." ], "summary": "Turn a logical UI action into validated fixed-tick intent and report completion without bypassing the owning game service.", "title": "Submit and observe a normal command", "url": "/api/v1/guides/guide.normal-command.html" }, { "example": "local completion_subscription = nil\n\nfunction initialize_package()\n completion_subscription = events.listen(\n \"events.command.completed\",\n function(event)\n feedback = event.payload.command_id .. \" completed\"\n end\n )\nend\n\nfunction shutdown_package()\n if completion_subscription ~= nil then\n events.ignore(completion_subscription)\n completion_subscription = nil\n end\nend", "id": "guide.listen-event", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "notes": [ "Events report immutable facts after mutation; handlers cannot cancel, replace, or intercept owner control flow.", "Delivery is ordered by event sequence, package dependency order, and subscription creation order.", "Every handler runs under Lua protected-call, instruction, memory, query, command, and event budgets. Repeated faults disable only the offending package.", "events.after remains available for bounded catch-up and diagnostics when active delivery was missed." ], "related": [ "events.listen", "events.ignore", "events.after", "events.command.completed", "command.submit" ], "steps": [ "Choose a registered event ID and confirm its payload fields in the API Reference.", "Register one bounded callback with events.listen during package initialization.", "Treat the detached event table as read-only application data. It contains no engine references, and edits cannot change the source event or another callback's copy.", "If the handler requests follow-up behavior, submit a typed command; it cannot execute before a later fixed tick.", "Remove an optional listener with events.ignore, or let reload and shutdown destroy the complete Lua generation." ], "summary": "Register a generation-scoped handler for an immutable owner fact without placing gameplay control flow inside the event chain.", "title": "Listen for a post-commit event", "url": "/api/v1/guides/guide.listen-event.html" }, { "example": "local receipt = restricted.command.submit(\n \"restricted.actor.crisis-override\",\n {\n actor_id = actor.actor_id,\n expected_actor_revision = actor.revision,\n expected_authority_revision = actor.authority_revision\n },\n 1\n)", "id": "guide.restricted-command", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "notes": [ "The host creates and validates package origin; Lua cannot promote itself.", "Restricted commands still route through typed validation, budgets, receipts, fixed ticks, and authoritative owners.", "Phase 14 permits development packages globally; a later end-user policy may narrow this authority without changing command ownership." ], "related": [ "restricted.command.submit", "restricted.actor.crisis-override", "error.restricted-command", "command.receipt" ], "steps": [ "Declare the package origin as development and validate that the restricted namespace is present.", "Query current target and authority revisions.", "Submit only a registered restricted command through restricted.command.submit.", "Observe the receipt and post-commit completion event through the normal evidence path.", "Handle error.restricted-command if the host origin does not authorize the call." ], "summary": "Exercise an explicitly restricted owner command during development without exposing it to standard packages.", "title": "Use a development-only restricted command", "url": "/api/v1/guides/guide.restricted-command.html" }, { "example": "function validate_package()\n assert(package_info.id == \"worldforge.resource-counts\")\n assert(type(settings.enabled) == \"boolean\")\nend\n\nfunction initialize_package()\n initialized = true\nend\n\nfunction suspend_package()\n assert(initialized)\nend\n\nfunction shutdown_package()\n initialized = false\nend", "id": "guide.reload-state", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "notes": [ "Lua globals belong to one VM generation and are not a persistence format.", "The host rejects stale-generation actions after a successful reload.", "A failed candidate never replaces the live VM, provider graph, or compatible settings." ], "related": [ "lifecycle.validate", "lifecycle.initialize", "lifecycle.suspend", "lifecycle.shutdown", "ui.action.packages.reload", "error.package-reload" ], "steps": [ "Keep durable settings in the manifest-declared settings schema instead of hidden globals.", "Declare a settings schema version and provide defaults for every field.", "Implement validate, initialize, suspend, and shutdown callbacks with bounded work and no owner mutation.", "Request reload through the compiled recovery action at a frame boundary.", "If validation fails, inspect diagnostics while the prior VM and composition graph remain active." ], "summary": "Design package state so transactional reload can validate a replacement VM and retain only version-compatible host-owned settings.", "title": "Preserve compatible state across reload", "url": "/api/v1/guides/guide.reload-state.html" }, { "example": "-- Recovery controls are compiled, not Lua-owned.\n-- Fix the package, then activate ui.action.packages.reload.\n-- If the replacement fails, the previous valid graph remains active.", "id": "guide.handle-fault", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "notes": [ "Diagnostic history is bounded and does not become simulation truth.", "Safe Mode disables package presentation while fixed-tick simulation continues.", "Do not implement recovery by directly editing owner state or by replacing the compiled shell." ], "related": [ "ui.action.packages.reload", "error.package-reload", "ui.surface.recovery", "ui.slot.recovery.status" ], "steps": [ "Open the compiled Scripts diagnostics panel and identify the package, callback, generation, and stable error ID.", "Correct the package source or manifest without changing gameplay owners.", "Reload packages; the host validates the candidate before replacing the live graph.", "If faults repeat, allow the host to disable only the failing package after its threshold.", "Use Safe Mode to remove scripted surfaces or restore the standard interface from the compiled shell." ], "summary": "Use bounded diagnostics, package isolation, Safe Mode, reload, and standard restoration without stopping simulation.", "title": "Diagnose and recover from a package fault", "url": "/api/v1/guides/guide.handle-fault.html" }, { "example": "local cursor = nil\nrepeat\n local result = world.query(\n \"world.job.info\",\n {page_size = 16, cursor = cursor}\n )\n assert(result.status == \"completed\", result.detail)\n for _, record in ipairs(result.records) do\n -- Consume detached records.\n end\n cursor = result.next_cursor\nuntil cursor == nil", "id": "guide.paginate-query", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "notes": [ "Cursors are opaque continuation values and are valid only for their registered query contract.", "Do not convert a presentation query into an every-frame scan of the whole world.", "Queries read owner-built snapshots and cannot repair or author missing facts." ], "related": [ "world.query", "world.job.info", "error.query-budget-exhausted", "error.capability-unavailable" ], "steps": [ "Choose a page size no larger than the data needed for one callback.", "Call world.query with the registered query ID and explicit filters.", "Consume records in returned stable order.", "If a next cursor is present, retain that opaque cursor and continue in a later bounded callback.", "Stop or degrade presentation when the query budget is exhausted or the capability is unavailable." ], "summary": "Traverse a detached owner snapshot without unbounded work or assumptions about container order.", "title": "Read a bounded query across pages", "url": "/api/v1/guides/guide.paginate-query.html" }, { "example": "{\n \"schema_version\": 1,\n \"id\": \"example.status-panel\",\n \"version\": \"1.0.0\",\n \"origin\": \"development\",\n \"entry\": \"main.lua\",\n \"api\": {\"minimum_major\": 1, \"maximum_major\": 1},\n \"dependencies\": [\"worldforge.standard-core\"]\n}", "id": "guide.package-checklist", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "notes": [ "Directory enumeration never grants load order or authority; validated identities and dependencies do.", "The runtime package root is user-accessible beside the launchers, while the compiled recovery interface remains outside it.", "A package must not retain raw engine pointers, ECS storage, renderer objects, or direct owner containers." ], "related": [ "lifecycle.validate", "world.query", "command.submit", "ui.surface.player-hud", "ui.action.packages.reload" ], "steps": [ "Create one directory under the runtime plugins root with manifest.json and its declared Lua entry file.", "Choose a stable package ID, origin, API major range, dependencies, lifecycle callbacks, settings schema, and UI contributions.", "Use only registered symbols available to that origin; filesystem, process, dynamic loading, and unrestricted standard libraries are absent.", "Validate callback balance, action registration, semantic metadata, query and command budgets, and memory limits.", "Reload transactionally, inspect diagnostics, and prove standard restoration and Safe Mode before distribution." ], "summary": "Follow the complete package path from manifest identity to bounded live composition and recovery proof.", "title": "Build and validate a package", "url": "/api/v1/guides/guide.package-checklist.html" }, { "example": "local channel_id = \"development.resource-activity\"\nlocal visible = world_indicators.is_visible(channel_id)\n\nfunction handle_action(action_id)\n if action_id == \"addon.resource-activity.toggle\" then\n world_indicators.set_visible(channel_id, not visible)\n end\nend", "id": "guide.world-indicators", "manual_nodes": [ "phase.17", "engine-reference.extension-contract" ], "notes": [ "Channel identities are compiled stable contracts. Packages discover and toggle channels but cannot register arbitrary simulation owners.", "The resource-activity channel is development-only and defaults to hidden.", "Indicator composition visits a bounded owner window only while its channel is visible.", "Indicator records are rebuilt from committed Resource, Supply, Work, and World facts; they are not saved as gameplay state." ], "related": [ "world_indicators.channels", "world_indicators.is-visible", "world_indicators.set-visible", "error.indicator-channel-authority", "error.indicator-channel-unavailable" ], "steps": [ "Call world_indicators.channels and show controls only for channels returned to the current package origin.", "Use a stable channel ID and world_indicators.is_visible to reflect its current per-session state.", "Change visibility from an explicit package action with world_indicators.set_visible.", "Treat indicator labels and values as detached presentation facts; do not infer write authority from them.", "Use Safe Mode when a development lens interferes with normal presentation; development-only channels are hidden with the development packages." ], "summary": "Discover and toggle host-owned world markers without moving simulation authority into Lua or rendering.", "title": "Control a world-indicator lens", "url": "/api/v1/guides/guide.world-indicators.html" }, { "example": "local candidates = world.query(\n \"world.infrastructure.maintenance\",\n {page_size = 8}\n)\nfor _, item in ipairs(candidates.records) do\n if item.eligible and item.work_kind == \"repair\" then\n command.submit(\n \"command.infrastructure.request-work\",\n {\n settlement_id = 1,\n infrastructure_id = item.infrastructure_id,\n kind = \"repair\"\n },\n 1\n )\n break\n end\nend", "id": "guide.control-infrastructure", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "notes": [ "Lua requests work; World retains condition, Settlement retains the choice, Construction retains progress, Work retains jobs and claims, Actor retains travel and labor, and Resource retains every physical unit.", "Broken roads provide no travel reduction. Broken fences and gates provide no enclosure or traversal effect until repair completes.", "Autonomous maintenance continues without Lua. Direction uses the same candidate and capacity checks rather than a separate mutation path.", "Use expected revisions for cancellation and gate policy changes. A retained query row is detached and may be stale by the command tick." ], "related": [ "world.infrastructure.local", "world.infrastructure.maintenance", "world.infrastructure.construction", "world.land.enclosures", "command.infrastructure.request-work", "command.infrastructure.cancel", "command.infrastructure.set-access-policy", "command.work.set-priority", "command.work.assign" ], "steps": [ "Query world.infrastructure.local for current identity, lifecycle, condition, geometry, access, and World revision facts.", "Query world.infrastructure.maintenance for the latest bounded Settlement candidate trace, condition wear evidence, resource readiness, and next autonomous evaluation tick.", "Submit command.infrastructure.request-work with one Settlement identity, infrastructure identity, and repair or extension kind when explicit direction is needed.", "Query world.infrastructure.construction for the designated project, worker, Work job, Resource containers, progress, and current project revision.", "Use command.work.set-priority or command.work.assign for normal labor direction, command.infrastructure.cancel for revision-checked cancellation, and command.infrastructure.set-access-policy only for gate policy changes." ], "summary": "Inspect roads, fences, gates, condition causes, and physical work, then request repair or extension without bypassing simulation owners.", "title": "Inspect and direct infrastructure work", "url": "/api/v1/guides/guide.control-infrastructure.html" } ], "interface_layers": [ { "id": "interface.compiled-recovery", "layer": "compiled_recovery", "package_origin": null, "replaceable": false }, { "id": "interface.standard-package", "layer": "standard_package", "package_origin": "first_party_standard", "replaceable": true }, { "id": "interface.development-package", "layer": "development_package", "package_origin": "development", "replaceable": true } ], "package_origins": [ "first_party_standard", "development" ], "reference_version": "v1", "schema_version": 1, "symbols": [ { "authority": "request", "availability": "runtime API 1", "deprecated": null, "description": "Typed normal command requests and receipts.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Bounded by per-package command and queue limits; authoritative work occurs once through the fixed-tick owner.", "examples": [ "-- Access documented members through command.receipt." ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "command", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "command.receipt", "command.submit" ], "returns": "A stable namespace table containing only the documented child symbols available to this package origin.", "signature": "namespace command", "usage": "Use command only to reach its registered child contracts. The namespace itself performs no query, mutation, lifecycle transition, or drawing." }, "errors": [], "fields": [], "id": "command", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "namespace", "name": "Command", "namespace": "command", "owner": "app.script-command-service", "replacement": null, "side_effects": "none", "signature": "namespace command", "source_location": "src/app/script_api_catalog.cpp", "timing": "fixed_tick", "units": null, "url": "/api/v1/symbols/command.html" }, { "authority": "request", "availability": "runtime API 1", "deprecated": null, "description": "Typed normal requests that change Actor control through its owner.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Bounded by per-package command and queue limits; authoritative work occurs once through the fixed-tick owner.", "examples": [ "-- Access documented members through command.actor.release-control." ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "command.actor", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "command.actor.release-control", "command.actor.take-control" ], "returns": "A stable namespace table containing only the documented child symbols available to this package origin.", "signature": "namespace command.actor", "usage": "Use command.actor only to reach its registered child contracts. The namespace itself performs no query, mutation, lifecycle transition, or drawing." }, "errors": [], "fields": [], "id": "command.actor", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "namespace", "name": "Actor commands", "namespace": "command.actor", "owner": "game.control-authority", "replacement": null, "side_effects": "none", "signature": "namespace command.actor", "source_location": "src/app/script_api_catalog.cpp", "timing": "fixed_tick", "units": null, "url": "/api/v1/symbols/command.actor.html" }, { "authority": "request", "availability": "active-session", "deprecated": null, "description": "Requests release of direct player control through ControlAuthority.", "determinism": "record request and owner result in engine sequence order", "documentation": { "cost": "Bounded by per-package command and queue limits; authoritative work occurs once through the fixed-tick owner.", "examples": [ "local receipt = command.submit(\n \"command.actor.release-control\",\n {\n actor_id = ,\n expected_actor_revision = ,\n expected_authority_revision = \n },\n 1\n)" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "command.actor.release-control", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [ "actor_id: Actor identity whose control state will be changed.", "expected_actor_revision: Expected revision of the Actor state.", "expected_authority_revision: Expected revision of the Actor control-authority record." ], "related": [ "command.actor", "error.command-budget-exhausted", "error.command-owner-rejected", "error.command-queue-full", "error.invalid-command", "error.restricted-command" ], "returns": "A command receipt from the owning fixed-tick command service; acceptance does not mean the command has completed.", "signature": "command.actor.release-control(actor_id, expected_authority_revision, expected_actor_revision) -> command.receipt", "usage": "Submit command.actor.release-control through command.submit. Supply current expected revisions so the owning service can reject stale intent without partial mutation." }, "errors": [ "error.command-budget-exhausted", "error.command-owner-rejected", "error.command-queue-full", "error.invalid-command", "error.restricted-command" ], "fields": [ { "description": "Actor identity whose control state will be changed.", "id": "actor_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Expected revision of the Actor state.", "id": "expected_actor_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Expected revision of the Actor control-authority record.", "id": "expected_authority_revision", "required": true, "units": null, "value_type": "revision" } ], "id": "command.actor.release-control", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "command", "name": "Release control", "namespace": "command.actor", "owner": "game.control-authority", "replacement": null, "side_effects": "may resume the retained Actor plan and return autonomous authority", "signature": "command.actor.release-control(actor_id, expected_authority_revision, expected_actor_revision) -> command.receipt", "source_location": "src/app/script_command_service.cpp", "timing": "fixed_tick", "units": null, "url": "/api/v1/symbols/command.actor.release-control.html" }, { "authority": "request", "availability": "active-session", "deprecated": null, "description": "Requests direct player control of one Actor through ControlAuthority.", "determinism": "record request and owner result in engine sequence order", "documentation": { "cost": "Bounded by per-package command and queue limits; authoritative work occurs once through the fixed-tick owner.", "examples": [ "local receipt = command.submit(\n \"command.actor.take-control\",\n {\n actor_id = ,\n expected_actor_revision = ,\n expected_authority_revision = \n },\n 1\n)" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "command.actor.take-control", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [ "actor_id: Actor identity whose control state will be changed.", "expected_actor_revision: Expected revision of the Actor state.", "expected_authority_revision: Expected revision of the Actor control-authority record." ], "related": [ "command.actor", "error.command-budget-exhausted", "error.command-owner-rejected", "error.command-queue-full", "error.invalid-command", "error.restricted-command" ], "returns": "A command receipt from the owning fixed-tick command service; acceptance does not mean the command has completed.", "signature": "command.actor.take-control(actor_id, expected_authority_revision, expected_actor_revision) -> command.receipt", "usage": "Submit command.actor.take-control through command.submit. Supply current expected revisions so the owning service can reject stale intent without partial mutation." }, "errors": [ "error.command-budget-exhausted", "error.command-owner-rejected", "error.command-queue-full", "error.invalid-command", "error.restricted-command" ], "fields": [ { "description": "Actor identity whose control state will be changed.", "id": "actor_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Expected revision of the Actor state.", "id": "expected_actor_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Expected revision of the Actor control-authority record.", "id": "expected_authority_revision", "required": true, "units": null, "value_type": "revision" } ], "id": "command.actor.take-control", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "command", "name": "Take control", "namespace": "command.actor", "owner": "game.control-authority", "replacement": null, "side_effects": "may pause the Actor plan and enter direct control", "signature": "command.actor.take-control(actor_id, expected_authority_revision, expected_actor_revision) -> command.receipt", "source_location": "src/app/script_command_service.cpp", "timing": "fixed_tick", "units": null, "url": "/api/v1/symbols/command.actor.take-control.html" }, { "authority": "request", "availability": "runtime API 1", "deprecated": null, "description": "Typed normal construction designation and cancellation requests.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Constant-time namespace lookup.", "examples": [ "-- Submit through command.construction.designate or command.construction.cancel." ], "history": [ "1.5.0: Player construction direction added for Phase 16D." ], "id": "command.construction", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [], "related": [ "command.construction.designate", "command.construction.cancel", "command.submit" ], "returns": "The registered construction command contracts.", "signature": "namespace command.construction", "usage": "Use this namespace to submit normal construction designation and cancellation requests. The namespace does not mutate Construction itself." }, "errors": [], "fields": [], "id": "command.construction", "introduced": { "display": "1.5.0", "major": 1, "minor": 5, "patch": 0 }, "kind": "namespace", "name": "Construction commands", "namespace": "command.construction", "owner": "game.construction", "replacement": null, "side_effects": "none", "signature": "namespace command.construction", "source_location": "src/app/script_api_catalog.cpp", "timing": "fixed_tick", "units": null, "url": "/api/v1/symbols/command.construction.html" }, { "authority": "request", "availability": "active-session", "deprecated": null, "description": "Cancels one current construction project through its existing owners.", "determinism": "record request and owner result in engine sequence order", "documentation": { "cost": "One indexed Construction lookup and its bounded transactional cleanup.", "examples": [ "command.submit(\"command.construction.cancel\", {construction_id = project.construction_id}, 1)" ], "history": [ "1.5.0: Normal construction cancellation added for Phase 16D." ], "id": "command.construction.cancel", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [ "construction_id: current Construction identity." ], "related": [ "command.construction", "world.construction.active", "command.receipt" ], "returns": "A fixed-tick command receipt with the owner result.", "signature": "command.construction.cancel(construction_id) -> command.receipt", "usage": "Submit the current construction ID returned by world.construction.active. Construction validates current ownership and performs all Work, reservation, material, and footprint cleanup." }, "errors": [ "error.command-budget-exhausted", "error.command-owner-rejected", "error.command-queue-full", "error.invalid-command", "error.restricted-command" ], "fields": [ { "description": "Current construction identity.", "id": "construction_id", "required": true, "units": null, "value_type": "stable-id" } ], "id": "command.construction.cancel", "introduced": { "display": "1.5.0", "major": 1, "minor": 5, "patch": 0 }, "kind": "command", "name": "Cancel construction", "namespace": "command.construction", "owner": "game.construction", "replacement": null, "side_effects": "may release construction Work, reservations, and footprint occupancy", "signature": "command.construction.cancel(construction_id) -> command.receipt", "source_location": "src/app/script_command_service.cpp", "timing": "fixed_tick", "units": null, "url": "/api/v1/symbols/command.construction.cancel.html" }, { "authority": "request", "availability": "active-session", "deprecated": null, "description": "Designates one authored building on the World grid through Settlement and Construction.", "determinism": "record request and owner result in engine sequence order", "documentation": { "cost": "Bounded catalog, footprint, Settlement, Resource, Construction, and Work validation.", "examples": [ "command.submit(\"command.construction.designate\", {settlement_id = settlement.settlement_id, expected_settlement_revision = settlement.revision, definition_id = project.definition_id, origin_x = cursor.x, origin_y = cursor.y, orientation = 0}, 1)" ], "history": [ "1.5.0: Revision-checked building designation added for Phase 16D." ], "id": "command.construction.designate", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [ "settlement_id: current Settlement identity.", "expected_settlement_revision: current Settlement revision.", "definition_id: authored building definition.", "origin_x: signed World-grid X cell.", "origin_y: signed World-grid Y cell.", "orientation: north, east, south, or west as zero through three." ], "related": [ "command.construction", "world.project.alternatives", "world.construction.active" ], "returns": "A fixed-tick command receipt. Rejection retains no partial project.", "signature": "command.construction.designate(settlement_id, expected_settlement_revision, definition_id, origin_x, origin_y, orientation) -> command.receipt", "usage": "Submit an authored building alternative, current Settlement revision, and World-grid placement. Settlement, content, Construction, Work, Resource, and capacity checks run before one project commits." }, "errors": [ "error.command-budget-exhausted", "error.command-owner-rejected", "error.command-queue-full", "error.invalid-command", "error.restricted-command" ], "fields": [ { "description": "Authored building definition identity.", "id": "definition_id", "required": true, "units": null, "value_type": "string" }, { "description": "Expected Settlement revision.", "id": "expected_settlement_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "North, east, south, or west as zero through three.", "id": "orientation", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "World-grid X coordinate.", "id": "origin_x", "required": true, "units": "grid-cells", "value_type": "signed-integer" }, { "description": "World-grid Y coordinate.", "id": "origin_y", "required": true, "units": "grid-cells", "value_type": "signed-integer" }, { "description": "Settlement receiving the construction.", "id": "settlement_id", "required": true, "units": null, "value_type": "stable-id" } ], "id": "command.construction.designate", "introduced": { "display": "1.5.0", "major": 1, "minor": 5, "patch": 0 }, "kind": "command", "name": "Designate construction", "namespace": "command.construction", "owner": "game.construction", "replacement": null, "side_effects": "may create one validated construction project and its normal Work", "signature": "command.construction.designate(settlement_id, expected_settlement_revision, definition_id, origin_x, origin_y, orientation) -> command.receipt", "source_location": "src/app/script_command_service.cpp", "timing": "fixed_tick", "units": null, "url": "/api/v1/symbols/command.construction.designate.html" }, { "authority": "request", "availability": "runtime API 1", "deprecated": null, "description": "Typed requests that control retained road, fence, and gate projects.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Namespace lookup is constant-time and performs no owner work.", "examples": [ "-- Submit owner-validated repair, extension, cancellation, or gate access requests through this namespace." ], "history": [ "1.19.0: Infrastructure construction, maintenance direction, and gate-access commands added for Village Life M2 through M4." ], "id": "command.infrastructure", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [], "related": [ "command.infrastructure.cancel", "command.infrastructure.request-work", "command.infrastructure.set-access-policy", "command.submit", "world.infrastructure.maintenance" ], "returns": "The registered infrastructure command contracts available to the package.", "signature": "namespace command.infrastructure", "usage": "Use command.infrastructure to reach normal requests for retained local-infrastructure construction. The namespace performs no mutation by itself." }, "errors": [], "fields": [], "id": "command.infrastructure", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "namespace", "name": "Infrastructure commands", "namespace": "command.infrastructure", "owner": "game.infrastructure-construction", "replacement": null, "side_effects": "none", "signature": "namespace command.infrastructure", "source_location": "src/app/script_api_catalog.cpp", "timing": "fixed_tick", "units": null, "url": "/api/v1/symbols/command.infrastructure.html" }, { "authority": "request", "availability": "active-session", "deprecated": null, "description": "Cancels one current infrastructure project through Construction, Work, Actor, Resource, and World owners.", "determinism": "record request and owner result in engine sequence order", "documentation": { "cost": "One indexed project lookup plus bounded transactional cleanup through Construction, Work, Actor, Resource, and World.", "examples": [ "command.submit(\"command.infrastructure.cancel\", {infrastructure_id = project.infrastructure_id, expected_revision = project.revision}, 1)" ], "history": [ "1.19.0: Revision-checked infrastructure cancellation added for Village Life M2." ], "id": "command.infrastructure.cancel", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [ "infrastructure_id: current World local-infrastructure identity.", "expected_revision: current infrastructure-construction project revision." ], "related": [ "command.infrastructure", "world.infrastructure.construction", "world.infrastructure.local", "command.receipt" ], "returns": "A fixed-tick command receipt with the owner result. A stale revision or rejected owner transaction changes no state.", "signature": "command.infrastructure.cancel(infrastructure_id, expected_revision) -> command.receipt", "usage": "Cancel one current road, fence, or gate project using the infrastructure identity and project revision returned by world.infrastructure.construction. Construction coordinates Work release, Resource return, Actor handoff, and restoration of the World plan." }, "errors": [ "error.command-budget-exhausted", "error.command-owner-rejected", "error.command-queue-full", "error.invalid-command", "error.restricted-command" ], "fields": [ { "description": "Expected infrastructure-construction project revision.", "id": "expected_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Current World infrastructure identity.", "id": "infrastructure_id", "required": true, "units": null, "value_type": "stable-id" } ], "id": "command.infrastructure.cancel", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "command", "name": "Cancel infrastructure work", "namespace": "command.infrastructure", "owner": "game.infrastructure-construction", "replacement": null, "side_effects": "may release Work, return delivered materials, and restore the retained World plan", "signature": "command.infrastructure.cancel(infrastructure_id, expected_revision) -> command.receipt", "source_location": "src/app/script_command_service.cpp", "timing": "fixed_tick", "units": null, "url": "/api/v1/symbols/command.infrastructure.cancel.html" }, { "authority": "request", "availability": "active-session", "deprecated": null, "description": "Directs one Settlement to evaluate a specific repair or network extension through current World, Construction, Work, Resource, and labor facts.", "determinism": "record request and owner result in engine sequence order", "documentation": { "cost": "One bounded Settlement decision over the directed candidate plus indexed World, Resource, and Construction owner checks.", "examples": [ "command.submit(\"command.infrastructure.request-work\", {settlement_id = 1, infrastructure_id = item.infrastructure_id, kind = \"repair\"}, 1)" ], "history": [ "1.19.0: Settlement-owned repair and extension direction added for Village Life M4." ], "id": "command.infrastructure.request-work", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [ "settlement_id: Settlement responsible for the requested work.", "infrastructure_id: damaged, broken, or proposed World infrastructure identity.", "kind: repair or extension." ], "related": [ "command.infrastructure", "world.infrastructure.local", "world.infrastructure.maintenance", "world.infrastructure.construction", "command.receipt" ], "returns": "A fixed-tick command receipt with the Settlement and Construction owner result. Invalid kind, unavailable materials, occupied capacity, or mismatched lifecycle changes no work owner.", "signature": "command.infrastructure.request-work(settlement_id, infrastructure_id, kind) -> command.receipt", "usage": "Ask one Settlement to evaluate a specific damaged or proposed infrastructure record as repair or extension work. The same chooser verifies current condition, construction capacity, physical material custody, and the retained site inventory before it designates Work." }, "errors": [ "error.command-budget-exhausted", "error.command-owner-rejected", "error.command-queue-full", "error.invalid-command", "error.restricted-command" ], "fields": [ { "description": "Damaged, broken, or proposed World infrastructure identity.", "id": "infrastructure_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Requested work kind: repair or extension.", "id": "kind", "required": true, "units": null, "value_type": "string" }, { "description": "Settlement responsible for the requested work.", "id": "settlement_id", "required": true, "units": null, "value_type": "stable-id" } ], "id": "command.infrastructure.request-work", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "command", "name": "Request infrastructure work", "namespace": "command.infrastructure", "owner": "game.settlement", "replacement": null, "side_effects": "may retain a Settlement decision and designate one repair or extension project", "signature": "command.infrastructure.request-work(settlement_id, infrastructure_id, kind) -> command.receipt", "source_location": "src/app/script_command_service.cpp", "timing": "fixed_tick", "units": null, "url": "/api/v1/symbols/command.infrastructure.request-work.html" }, { "authority": "request", "availability": "active-session", "deprecated": null, "description": "Changes one gate to a validated World access policy through revision-checked World authority.", "determinism": "record request and World result in engine sequence order", "documentation": { "cost": "Indexed gate and policy lookups plus one bounded World navigation synchronization when the mutation succeeds.", "examples": [ "command.submit(\"command.infrastructure.set-access-policy\", {infrastructure_id = gate.infrastructure_id, expected_revision = gate.revision, access_policy_id = \"access.public\"}, 1)" ], "history": [ "1.19.0: Revision-checked gate access-policy control added for Village Life M3." ], "id": "command.infrastructure.set-access-policy", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [ "infrastructure_id: current World gate identity.", "expected_revision: current World gate revision.", "access_policy_id: validated authored World access-policy identity." ], "related": [ "command.infrastructure", "world.infrastructure.local", "world.land.enclosures", "command.receipt" ], "returns": "A fixed-tick command receipt with the World owner result. Unknown policies, non-gate targets, and stale revisions change no state.", "signature": "command.infrastructure.set-access-policy(infrastructure_id, expected_revision, access_policy_id) -> command.receipt", "usage": "Change one retained gate to a validated authored access policy. Submit the current gate identity and World revision from world.infrastructure.local; World applies the policy and updates traversability and field access atomically at the fixed tick." }, "errors": [ "error.command-budget-exhausted", "error.command-owner-rejected", "error.command-queue-full", "error.invalid-command", "error.restricted-command" ], "fields": [ { "description": "Validated authored World access-policy identity.", "id": "access_policy_id", "required": true, "units": null, "value_type": "string" }, { "description": "Expected World gate revision.", "id": "expected_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Current World gate identity.", "id": "infrastructure_id", "required": true, "units": null, "value_type": "stable-id" } ], "id": "command.infrastructure.set-access-policy", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "command", "name": "Set gate access policy", "namespace": "command.infrastructure", "owner": "sim.world", "replacement": null, "side_effects": "may change gate traversability and field access at the committed tick", "signature": "command.infrastructure.set-access-policy(infrastructure_id, expected_revision, access_policy_id) -> command.receipt", "source_location": "src/app/script_command_service.cpp", "timing": "fixed_tick", "units": null, "url": "/api/v1/symbols/command.infrastructure.set-access-policy.html" }, { "authority": "request", "availability": "runtime API 1", "deprecated": null, "description": "Typed normal requests that move conserved currency through Resource.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Namespace lookup is constant-time and performs no owner work.", "examples": [ "-- Submit a contribution through command.money.contribute." ], "history": [ "1.4.0: Normal conserved money command namespace added for Phase 16D2." ], "id": "command.money", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [], "related": [ "command.money.contribute", "command.submit" ], "returns": "The documented money command contracts available to the package.", "signature": "namespace command.money", "usage": "Use command.money to reach normal player money requests. The namespace performs no transfer by itself." }, "errors": [], "fields": [], "id": "command.money", "introduced": { "display": "1.4.0", "major": 1, "minor": 4, "patch": 0 }, "kind": "namespace", "name": "Money commands", "namespace": "command.money", "owner": "game.resource-economy", "replacement": null, "side_effects": "none", "signature": "namespace command.money", "source_location": "src/app/script_api_catalog.cpp", "timing": "fixed_tick", "units": null, "url": "/api/v1/symbols/command.money.html" }, { "authority": "request", "availability": "active-session", "deprecated": null, "description": "Requests one conserved transfer from a directly controlled Actor wallet to that Actor's Household.", "determinism": "record request and Resource result in engine sequence order; request sequence is the stable custody-transfer identity", "documentation": { "cost": "One bounded membership and authority check, two indexed custody lookups, and one atomic Resource transfer.", "examples": [ "local receipt = command.submit(\"command.money.contribute\", {\n actor_id = actor.actor_id,\n household_id = household.household_id,\n currency_definition_id = personal.currency_definition_id,\n amount_minor_units = 1,\n expected_authority_revision = actor.authority_revision,\n expected_household_revision = household.revision,\n expected_personal_custody_revision = personal.container_revision,\n expected_household_custody_revision = shared.container_revision\n}, 1)" ], "history": [ "1.4.0: Actor-to-own-Household contribution added for Phase 16D2." ], "id": "command.money.contribute", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [ "actor_id: contributing Actor.", "household_id: Actor's own Household.", "currency_definition_id: authored currency identity.", "amount_minor_units: positive exact amount.", "expected_authority_revision: current direct-control revision.", "expected_household_revision: current Household revision.", "expected_personal_custody_revision: current Actor-wallet revision.", "expected_household_custody_revision: current Household-money revision." ], "related": [ "command.money", "world.actor.wealth", "world.household.wealth", "events.money.transferred" ], "returns": "A fixed-tick command receipt. Completion produces events.money.transferred followed by events.command.completed.", "signature": "command.money.contribute(actor_id, household_id, currency_definition_id, amount_minor_units, expected_authority_revision, expected_household_revision, expected_personal_custody_revision, expected_household_custody_revision) -> command.receipt", "usage": "Submit a contribution only after the player explicitly takes control of the Actor. Use detached Actor, Household, and money queries to supply current stable IDs and revisions." }, "errors": [ "error.command-budget-exhausted", "error.command-owner-rejected", "error.command-queue-full", "error.invalid-command", "error.restricted-command" ], "fields": [ { "description": "Actor whose personal wallet supplies the contribution.", "id": "actor_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Exact contribution amount.", "id": "amount_minor_units", "required": true, "units": "minor-currency-units", "value_type": "unsigned-integer" }, { "description": "Authored currency definition identity.", "id": "currency_definition_id", "required": true, "units": null, "value_type": "string" }, { "description": "Expected Actor control-authority revision.", "id": "expected_authority_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Expected Household-money revision.", "id": "expected_household_custody_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Expected Household membership revision.", "id": "expected_household_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Expected Actor-wallet revision.", "id": "expected_personal_custody_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Actor Household that receives the contribution.", "id": "household_id", "required": true, "units": null, "value_type": "stable-id" } ], "id": "command.money.contribute", "introduced": { "display": "1.4.0", "major": 1, "minor": 4, "patch": 0 }, "kind": "command", "name": "Contribute money", "namespace": "command.money", "owner": "game.resource-economy", "replacement": null, "side_effects": "may move exact currency units from Actor custody to that Actor's Household custody", "signature": "command.money.contribute(actor_id, household_id, currency_definition_id, amount_minor_units, expected_authority_revision, expected_household_revision, expected_personal_custody_revision, expected_household_custody_revision) -> command.receipt", "source_location": "src/app/script_command_service.cpp", "timing": "fixed_tick", "units": null, "url": "/api/v1/symbols/command.money.contribute.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Reports validation and owner completion for a typed command.", "determinism": "ordered by engine-assigned receipt sequence", "documentation": { "cost": "Bounded by per-package command and queue limits; authoritative work occurs once through the fixed-tick owner.", "examples": [ "local receipt = command.submit(\"command.actor.take-control\", arguments, 1)\nif receipt.status == \"accepted\" then\n -- Wait for the corresponding completion event.\nend" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "command.receipt", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "command", "command.submit", "events.command.completed" ], "returns": "An immutable receipt record describing a submitted command and its current status.", "signature": "command.receipt", "usage": "Keep the receipt sequence and status as request evidence. Use post-commit events for completion; an accepted receipt is not authoritative completion." }, "errors": [], "fields": [ { "description": "Committed simulation tick when the receipt was recorded.", "id": "recorded_at_tick", "required": true, "units": "simulation-ticks", "value_type": "tick" }, { "description": "Engine-assigned command request sequence.", "id": "request_sequence", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Engine-assigned receipt sequence.", "id": "sequence", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Submitted, accepted, rejected, completed, or failed.", "id": "status", "required": true, "units": null, "value_type": "string" } ], "id": "command.receipt", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "receipt", "name": "Command receipt", "namespace": "command", "owner": "app.script-command-service", "replacement": null, "side_effects": "none", "signature": "command.receipt", "source_location": "src/app/script_command_service.cpp", "timing": "post_commit", "units": null, "url": "/api/v1/symbols/command.receipt.html" }, { "authority": "request", "availability": "Phase 14 package callbacks", "deprecated": null, "description": "Submits one normal command with host-created package origin.", "determinism": "Host-created package identity and per-callback budgets.", "documentation": { "cost": "Bounded by per-package command and queue limits; authoritative work occurs once through the fixed-tick owner.", "examples": [ "local receipt = command.submit(\"command.actor.take-control\", arguments, 1)" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "command.submit", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [ "command_id: stable ID of a registered command.", "arguments: table matching the command descriptor fields.", "delay_ticks: optional bounded delay from the next fixed tick." ], "related": [ "command", "error.command-budget-exhausted", "error.invalid-command", "command.receipt", "events.command.completed" ], "returns": "A host-created receipt with request sequence, command ID, target tick, origin, and accepted status.", "signature": "command.submit(command_id, arguments, delay_ticks?) -> receipt", "usage": "Submit a normal registered command. The host creates the origin and receipt; the owning game service applies valid intent at a fixed tick." }, "errors": [ "error.command-budget-exhausted", "error.invalid-command" ], "fields": [], "id": "command.submit", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "function", "name": "submit", "namespace": "command", "owner": "app.ScriptPackageHost", "replacement": null, "side_effects": "submits a validated request to the existing command service", "signature": "command.submit(command_id, arguments, delay_ticks?) -> receipt", "source_location": "src/app/script_package_host.cpp", "timing": "fixed_tick", "units": null, "url": "/api/v1/symbols/command.submit.html" }, { "authority": "request", "availability": "runtime API 1", "deprecated": null, "description": "Typed normal requests for Work assignment, cancellation, and priority.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Constant-time namespace lookup.", "examples": [ "-- Submit through command.work.assign, command.work.cancel, or command.work.set-priority." ], "history": [ "1.5.0: Player Work direction namespace added for Phase 16D." ], "id": "command.work", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [], "related": [ "command.work.assign", "command.work.cancel", "command.work.set-priority" ], "returns": "The registered Work command contracts.", "signature": "namespace command.work", "usage": "Use this namespace for bounded player assignment, cancellation, and durable job-priority requests. Work remains authoritative for every result." }, "errors": [], "fields": [], "id": "command.work", "introduced": { "display": "1.5.0", "major": 1, "minor": 5, "patch": 0 }, "kind": "namespace", "name": "Work commands", "namespace": "command.work", "owner": "game.work-lifecycle", "replacement": null, "side_effects": "none", "signature": "namespace command.work", "source_location": "src/app/script_api_catalog.cpp", "timing": "fixed_tick", "units": null, "url": "/api/v1/symbols/command.work.html" }, { "authority": "request", "availability": "active-session", "deprecated": null, "description": "Assigns one current visible Work job to one Actor through the retained order path.", "determinism": "record request and Work result in engine sequence order", "documentation": { "cost": "Bounded indexed validation across Actor, Work, World, and ControlAuthority.", "examples": [ "command.submit(\"command.work.assign\", target, 1)" ], "history": [ "1.5.0: Player assignment to visible settlement work added for Phase 16D." ], "id": "command.work.assign", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [ "actor_id: target Actor.", "expected_actor_revision: current Actor revision.", "job_id: visible Work job.", "expected_job_revision: current job revision.", "work_task_id: first target Work task.", "expected_task_revision: current task revision.", "target_site_id: target Site.", "expected_topology_revision: current World topology revision." ], "related": [ "command.work", "world.work.targets", "world.work.assignment" ], "returns": "A fixed-tick receipt for a durable player assignment-order request.", "signature": "command.work.assign(actor_id, expected_actor_revision, job_id, expected_job_revision, work_task_id, expected_task_revision, target_site_id, expected_topology_revision) -> command.receipt", "usage": "Use one current row from world.work.targets without altering its stable IDs or revisions. The normal assignment-order path decides whether the Actor can accept the work." }, "errors": [ "error.command-budget-exhausted", "error.command-owner-rejected", "error.command-queue-full", "error.invalid-command", "error.restricted-command" ], "fields": [ { "description": "Actor receiving the work direction.", "id": "actor_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Expected Actor owner revision.", "id": "expected_actor_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Expected Work job revision.", "id": "expected_job_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Expected Work task revision.", "id": "expected_task_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Expected World topology revision.", "id": "expected_topology_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Current visible Work job.", "id": "job_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "World Site that owns the work target.", "id": "target_site_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "First task of the selected job.", "id": "work_task_id", "required": true, "units": null, "value_type": "stable-id" } ], "id": "command.work.assign", "introduced": { "display": "1.5.0", "major": 1, "minor": 5, "patch": 0 }, "kind": "command", "name": "Assign work", "namespace": "command.work", "owner": "game.work-lifecycle", "replacement": null, "side_effects": "may create and activate one durable player assignment order", "signature": "command.work.assign(actor_id, expected_actor_revision, job_id, expected_job_revision, work_task_id, expected_task_revision, target_site_id, expected_topology_revision) -> command.receipt", "source_location": "src/app/script_command_service.cpp", "timing": "fixed_tick", "units": null, "url": "/api/v1/symbols/command.work.assign.html" }, { "authority": "request", "availability": "active-session", "deprecated": null, "description": "Cancels one current player assignment through Work.", "determinism": "record request and Work result in engine sequence order", "documentation": { "cost": "One indexed assignment lookup and bounded owner reconciliation.", "examples": [ "command.submit(\"command.work.cancel\", {order_id = assignment.order_id, expected_order_revision = assignment.order_revision}, 1)" ], "history": [ "1.5.0: Player Work cancellation added for Phase 16D." ], "id": "command.work.cancel", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [ "order_id: current assignment-order identity.", "expected_order_revision: current order revision." ], "related": [ "command.work", "world.work.assignment", "command.receipt" ], "returns": "A fixed-tick receipt with the cancellation result.", "signature": "command.work.cancel(order_id, expected_order_revision) -> command.receipt", "usage": "Cancel the current live player assignment returned by world.work.assignment. Work and ControlAuthority reconcile the Actor without deleting the underlying autonomous job." }, "errors": [ "error.command-budget-exhausted", "error.command-owner-rejected", "error.command-queue-full", "error.invalid-command", "error.restricted-command" ], "fields": [ { "description": "Expected assignment-order revision.", "id": "expected_order_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Current assignment-order identity.", "id": "order_id", "required": true, "units": null, "value_type": "stable-id" } ], "id": "command.work.cancel", "introduced": { "display": "1.5.0", "major": 1, "minor": 5, "patch": 0 }, "kind": "command", "name": "Cancel work assignment", "namespace": "command.work", "owner": "game.work-lifecycle", "replacement": null, "side_effects": "may release one queued or active player assignment", "signature": "command.work.cancel(order_id, expected_order_revision) -> command.receipt", "source_location": "src/app/script_command_service.cpp", "timing": "fixed_tick", "units": null, "url": "/api/v1/symbols/command.work.cancel.html" }, { "authority": "request", "availability": "active-session", "deprecated": null, "description": "Sets one durable player-priority contribution on a current Work job.", "determinism": "record request and Work result in engine sequence order", "documentation": { "cost": "One indexed job lookup and one revision-checked mutation.", "examples": [ "command.submit(\"command.work.set-priority\", {job_id = target.job_id, expected_job_revision = target.job_revision, priority_basis_points = 10000}, 1)" ], "history": [ "1.5.0: Durable player job priority added for Phase 16D." ], "id": "command.work.set-priority", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [ "job_id: current Work job.", "expected_job_revision: current job revision.", "priority_basis_points: value from zero through ten thousand." ], "related": [ "command.work", "world.work.targets", "world.job.info" ], "returns": "A fixed-tick receipt containing the Work owner result.", "signature": "command.work.set-priority(job_id, expected_job_revision, priority_basis_points) -> command.receipt", "usage": "Set a bounded durable preference contribution on one current job. The reasoner combines it with normal need, distance, capability, and habit considerations rather than forcing an assignment." }, "errors": [ "error.command-budget-exhausted", "error.command-owner-rejected", "error.command-queue-full", "error.invalid-command", "error.restricted-command" ], "fields": [ { "description": "Expected Work job revision.", "id": "expected_job_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Current Work job.", "id": "job_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Player priority contribution from zero through ten thousand.", "id": "priority_basis_points", "required": true, "units": "basis-points", "value_type": "unsigned-integer" } ], "id": "command.work.set-priority", "introduced": { "display": "1.5.0", "major": 1, "minor": 5, "patch": 0 }, "kind": "command", "name": "Set work priority", "namespace": "command.work", "owner": "game.work-lifecycle", "replacement": null, "side_effects": "may change later bounded autonomous job scoring", "signature": "command.work.set-priority(job_id, expected_job_revision, priority_basis_points) -> command.receipt", "source_location": "src/app/script_command_service.cpp", "timing": "fixed_tick", "units": null, "url": "/api/v1/symbols/command.work.set-priority.html" }, { "authority": "read_only", "availability": "runtime API 1", "deprecated": null, "description": "Bounded diagnostics available to development packages.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Namespace lookup is constant-time and performs no owner work.", "examples": [ "-- Access documented members through developer.runtime." ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "developer", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "developer.runtime" ], "returns": "A stable namespace table containing only the documented child symbols available to this package origin.", "signature": "namespace developer", "usage": "Use developer only to reach its registered child contracts. The namespace itself performs no query, mutation, lifecycle transition, or drawing." }, "errors": [], "fields": [], "id": "developer", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "namespace", "name": "Developer", "namespace": "developer", "owner": "app.runtime-session", "replacement": null, "side_effects": "none", "signature": "namespace developer", "source_location": "src/app/script_api_catalog.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/developer.html" }, { "authority": "read_only", "availability": "runtime API 1", "deprecated": null, "description": "Detached scenario capacity limits, observed use, and policy revision.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "No owner work.", "examples": [ "-- Query developer.capacity-policy.current through world.query." ], "history": [ "1.2.0: Capacity-policy namespace added." ], "id": "developer.capacity-policy", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [], "related": [ "developer.capacity-policy.current" ], "returns": "The capacity-policy query contracts.", "signature": "namespace developer.capacity-policy", "usage": "Inspect detached scenario capacity limits and observed use." }, "errors": [], "fields": [], "id": "developer.capacity-policy", "introduced": { "display": "1.2.0", "major": 1, "minor": 2, "patch": 0 }, "kind": "namespace", "name": "Developer capacity policy", "namespace": "developer.capacity-policy", "owner": "app.scenario-capacity-policy", "replacement": null, "side_effects": "none", "signature": "namespace developer.capacity-policy", "source_location": "src/app/script_api_catalog.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/developer.capacity-policy.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns the current scenario capacity limits, observed use, and policy revision.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "One bounded query and owner visit.", "examples": [ "local result = world.query(\"developer.capacity-policy.current\", {page_size = 1})" ], "history": [ "1.2.0: Capacity-policy query added." ], "id": "developer.capacity-policy.current", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [ "filters: none.", "cursor: zero.", "page_size: bounded record limit." ], "related": [ "restricted.capacity-policy.set-limit", "events.capacity-policy.changed" ], "returns": "One detached capacity-policy record.", "signature": "developer.capacity-policy.current(filters?, cursor?, page_size?) -> query-page", "usage": "Read current population, resource, per-container, and aggregate-storage limits, use, and revision." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Maximum permitted capacity of one inventory container.", "id": "container_capacity_limit", "required": true, "units": "resource-units", "value_type": "unsigned-integer" }, { "description": "Largest observed inventory-container capacity.", "id": "largest_container_capacity", "required": true, "units": "resource-units", "value_type": "unsigned-integer" }, { "description": "Maximum permitted live population.", "id": "population_limit", "required": true, "units": "actors", "value_type": "unsigned-integer" }, { "description": "Observed live population.", "id": "population_usage", "required": true, "units": "actors", "value_type": "unsigned-integer" }, { "description": "Maximum permitted aggregate resource quantity.", "id": "resource_units_limit", "required": true, "units": "resource-units", "value_type": "unsigned-integer" }, { "description": "Observed aggregate resource quantity.", "id": "resource_units_usage", "required": true, "units": "resource-units", "value_type": "unsigned-integer" }, { "description": "Current capacity-policy revision.", "id": "revision", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Maximum permitted aggregate inventory capacity.", "id": "storage_capacity_limit", "required": true, "units": "resource-units", "value_type": "unsigned-integer" }, { "description": "Observed aggregate inventory capacity.", "id": "storage_capacity_usage", "required": true, "units": "resource-units", "value_type": "unsigned-integer" } ], "id": "developer.capacity-policy.current", "introduced": { "display": "1.2.0", "major": 1, "minor": 2, "patch": 0 }, "kind": "query", "name": "Current capacity policy", "namespace": "developer.capacity-policy", "owner": "app.scenario-capacity-policy", "replacement": null, "side_effects": "none", "signature": "developer.capacity-policy.current(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/developer.capacity-policy.current.html" }, { "authority": "read_only", "availability": "runtime API 1", "deprecated": null, "description": "Detached current and bounded logged frame, CPU, and process-memory diagnostics.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Namespace lookup is constant-time and performs no measurement or owner work.", "examples": [ "-- Query developer.performance.current through world.query." ], "history": [ "1.0.0: Current and bounded logged performance diagnostics added during Phase 15 closure." ], "id": "developer.performance", "manual_nodes": [ "phase.15", "engine-reference.extension-contract" ], "parameters": [], "related": [ "developer", "developer.performance.current", "developer.performance.log", "developer.performance.log-samples", "performance" ], "returns": "A stable namespace table containing the documented performance query identities.", "signature": "namespace developer.performance", "usage": "Use developer.performance only to reach current and bounded logged performance queries. The namespace itself records no samples and changes no logging state." }, "errors": [], "fields": [], "id": "developer.performance", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "namespace", "name": "Developer performance", "namespace": "developer.performance", "owner": "app.runtime-performance-monitor", "replacement": null, "side_effects": "none", "signature": "namespace developer.performance", "source_location": "src/app/script_api_catalog.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/developer.performance.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns a continuously updated rolling frame, CPU, and process-memory snapshot.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "Aggregates at most 120 retained frame samples and consumes one query, one result record, and one owner visit per included sample.", "examples": [ "local result = world.query(\"developer.performance.current\", {page_size = 1})\nif result.status == \"completed\" then\n local current = result.records[1]\n ui.row(\"FPS\", string.format(\"%.1f\", current.frames_per_second))\n ui.row(\"Memory\", tostring(current.resident_memory_bytes))\nend" ], "history": [ "1.0.0: Current frame, CPU, and process-memory telemetry added during Phase 15 closure." ], "id": "developer.performance.current", "manual_nodes": [ "phase.15", "engine-reference.extension-contract" ], "parameters": [ "cursor: must remain zero for the single current record.", "page_size: positive record limit capped by the host; one record is returned.", "filters: no filters are accepted." ], "related": [ "developer.performance", "developer.performance.log", "performance.start-logging", "world.query", "error.capability-unavailable" ], "returns": "One detached current record after at least one frame has been presented, or error.capability-unavailable before then.", "signature": "developer.performance.current(filters?, cursor?, page_size?) -> query-page", "usage": "Call through world.query to read the latest rolling FPS, frame time, process CPU, process resident-memory, and logging-state snapshot. Treat values as nondeterministic presentation diagnostics, not simulation facts." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Rolling process CPU time per frame.", "id": "average_cpu_ms", "required": true, "units": "milliseconds", "value_type": "number" }, { "description": "Rolling average frame duration.", "id": "average_frame_ms", "required": true, "units": "milliseconds", "value_type": "number" }, { "description": "Rolling process CPU time relative to wall time.", "id": "cpu_percent", "required": true, "units": "percent-of-one-core", "value_type": "number" }, { "description": "Rolling average frame rate.", "id": "frames_per_second", "required": true, "units": "frames-per-second", "value_type": "number" }, { "description": "Latest recorded frame index.", "id": "latest_frame", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Latest frame duration.", "id": "latest_frame_ms", "required": true, "units": "milliseconds", "value_type": "number" }, { "description": "Whether a bounded logging session is active.", "id": "logging_active", "required": true, "units": null, "value_type": "boolean" }, { "description": "Current or most recent logging session identity.", "id": "logging_session_id", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Whether current resident memory is available.", "id": "memory_available", "required": true, "units": null, "value_type": "boolean" }, { "description": "Current process resident memory when available.", "id": "resident_memory_bytes", "required": true, "units": "bytes", "value_type": "unsigned-integer" }, { "description": "Samples in the rolling window.", "id": "sample_count", "required": true, "units": null, "value_type": "unsigned-integer" } ], "id": "developer.performance.current", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "query", "name": "Current performance", "namespace": "developer.performance", "owner": "app.runtime-performance-monitor", "replacement": null, "side_effects": "none", "signature": "developer.performance.current(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/developer.performance.current.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns min, average, and max values for the current or most recent bounded log.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "Reads a constant-time rolling summary maintained while recording and consumes one query, one result record, and one owner visit.", "examples": [ "local result = world.query(\"developer.performance.log\", {page_size = 1})\nif result.status == \"completed\" then\n local log = result.records[1]\n ui.row(\"Minimum FPS\", string.format(\"%.1f\", log.minimum_fps))\n ui.row(\"Maximum memory\", tostring(log.maximum_memory_bytes))\nend" ], "history": [ "1.0.0: Bounded performance-log summaries added during Phase 15 closure." ], "id": "developer.performance.log", "manual_nodes": [ "phase.15", "engine-reference.extension-contract" ], "parameters": [ "cursor: must remain zero for the single summary record.", "page_size: positive record limit capped by the host; one record is returned.", "filters: no filters are accepted." ], "related": [ "developer.performance", "developer.performance.log-samples", "performance.start-logging", "performance.stop-logging", "world.query" ], "returns": "One detached summary for the active or most recent log, including state, session identity, sample count, capacity, frame bounds, and metric ranges.", "signature": "developer.performance.log(filters?, cursor?, page_size?) -> query-page", "usage": "Call through world.query while a logging session is active or after it stops. Read min, average, and max FPS, frame time, process CPU, and resident-memory values without retaining native handles." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Average process CPU time.", "id": "average_cpu_ms", "required": true, "units": "milliseconds", "value_type": "number" }, { "description": "Average process CPU load.", "id": "average_cpu_percent", "required": true, "units": "percent-of-one-core", "value_type": "number" }, { "description": "Average instantaneous frame rate.", "id": "average_fps", "required": true, "units": "frames-per-second", "value_type": "number" }, { "description": "Average frame duration.", "id": "average_frame_ms", "required": true, "units": "milliseconds", "value_type": "number" }, { "description": "Average resident memory.", "id": "average_memory_bytes", "required": true, "units": "bytes", "value_type": "unsigned-integer" }, { "description": "Latest resident memory.", "id": "latest_memory_bytes", "required": true, "units": "bytes", "value_type": "unsigned-integer" }, { "description": "Maximum process CPU time.", "id": "maximum_cpu_ms", "required": true, "units": "milliseconds", "value_type": "number" }, { "description": "Maximum process CPU load.", "id": "maximum_cpu_percent", "required": true, "units": "percent-of-one-core", "value_type": "number" }, { "description": "Maximum instantaneous frame rate.", "id": "maximum_fps", "required": true, "units": "frames-per-second", "value_type": "number" }, { "description": "Maximum frame duration.", "id": "maximum_frame_ms", "required": true, "units": "milliseconds", "value_type": "number" }, { "description": "Maximum resident memory.", "id": "maximum_memory_bytes", "required": true, "units": "bytes", "value_type": "unsigned-integer" }, { "description": "Configured sample capacity.", "id": "maximum_samples", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Samples with available resident memory.", "id": "memory_sample_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Minimum process CPU time.", "id": "minimum_cpu_ms", "required": true, "units": "milliseconds", "value_type": "number" }, { "description": "Minimum process CPU load.", "id": "minimum_cpu_percent", "required": true, "units": "percent-of-one-core", "value_type": "number" }, { "description": "Minimum instantaneous frame rate.", "id": "minimum_fps", "required": true, "units": "frames-per-second", "value_type": "number" }, { "description": "Minimum frame duration.", "id": "minimum_frame_ms", "required": true, "units": "milliseconds", "value_type": "number" }, { "description": "Minimum resident memory.", "id": "minimum_memory_bytes", "required": true, "units": "bytes", "value_type": "unsigned-integer" }, { "description": "Recorded sample count.", "id": "sample_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Logging session identity.", "id": "session_id", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "First eligible frame index.", "id": "started_frame", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Logging state.", "id": "state", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Last recorded frame or zero while active.", "id": "stopped_frame", "required": true, "units": null, "value_type": "unsigned-integer" } ], "id": "developer.performance.log", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "query", "name": "Performance log summary", "namespace": "developer.performance", "owner": "app.runtime-performance-monitor", "replacement": null, "side_effects": "none", "signature": "developer.performance.log(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/developer.performance.log.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns one bounded page of frame, CPU, and process-memory samples from the current or most recent log.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "Copies at most 64 samples per call and consumes matching query-record and owner-visit budgets.", "examples": [ "local result = world.query(\"developer.performance.log-samples\", {cursor = 0, page_size = 16})\nfor _, sample in ipairs(result.records) do\n ui.row(\"Frame \" .. tostring(sample.frame), string.format(\"%.2f ms\", sample.frame_ms))\nend" ], "history": [ "1.0.0: Paginated bounded performance-log samples added during Phase 15 closure." ], "id": "developer.performance.log-samples", "manual_nodes": [ "phase.15", "engine-reference.extension-contract" ], "parameters": [ "cursor: optional continuation cursor returned by this query.", "page_size: positive sample limit capped at 64 by the host.", "filters: no filters are accepted." ], "related": [ "developer.performance", "developer.performance.log", "performance.start-logging", "performance.stop-logging", "world.query" ], "returns": "A detached page of frame index, instantaneous FPS, frame time, process CPU time and load, and resident-memory samples.", "signature": "developer.performance.log-samples(filters?, cursor?, page_size?) -> query-page", "usage": "Call through world.query to page through the active or most recent bounded logging session. Consume detached samples during the callback and use next_cursor for continuation." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Process CPU time.", "id": "cpu_ms", "required": true, "units": "milliseconds", "value_type": "number" }, { "description": "Process CPU time relative to wall time.", "id": "cpu_percent", "required": true, "units": "percent-of-one-core", "value_type": "number" }, { "description": "Recorded frame index.", "id": "frame", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Frame duration.", "id": "frame_ms", "required": true, "units": "milliseconds", "value_type": "number" }, { "description": "Instantaneous frame rate.", "id": "frames_per_second", "required": true, "units": "frames-per-second", "value_type": "number" }, { "description": "Whether resident memory was available.", "id": "memory_available", "required": true, "units": null, "value_type": "boolean" }, { "description": "Process resident memory.", "id": "resident_memory_bytes", "required": true, "units": "bytes", "value_type": "unsigned-integer" } ], "id": "developer.performance.log-samples", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "query", "name": "Performance log samples", "namespace": "developer.performance", "owner": "app.runtime-performance-monitor", "replacement": null, "side_effects": "none", "signature": "developer.performance.log-samples(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/developer.performance.log-samples.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns bounded scheduler and frame diagnostics.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "Bounded by page size, per-package query budget, and the owning snapshot builder; results are detached before Lua receives them.", "examples": [ "local result = world.query(\"developer.runtime\", {page_size = 16})\nif result.status == \"completed\" then\n for _, record in ipairs(result.records) do\n -- Render or inspect detached record fields here.\n end\nend" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "developer.runtime", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [ "filters: optional table of query-specific stable IDs and bounded selectors.", "cursor: optional opaque continuation cursor returned by the same query.", "page_size: optional positive record limit capped by the host." ], "related": [ "developer", "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation", "world.query" ], "returns": "A detached query page with status, records, continuation metadata, and a stable diagnostic when the request cannot complete.", "signature": "developer.runtime(filters?, cursor?, page_size?) -> query-page", "usage": "Call this query through world.query with the stable ID developer.runtime. Consume detached records during the current callback and use the returned cursor for bounded continuation." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Whether compiled diagnostics are visible.", "id": "diagnostics_visible", "required": true, "units": null, "value_type": "boolean" }, { "description": "Observed platform event count.", "id": "event_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Rendered frame count.", "id": "frame_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Last frame duration.", "id": "frame_ms", "required": true, "units": "milliseconds", "value_type": "number" }, { "description": "Whether fixed ticks are paused.", "id": "paused", "required": true, "units": null, "value_type": "boolean" }, { "description": "Last simulation duration.", "id": "sim_ms", "required": true, "units": "milliseconds", "value_type": "number" }, { "description": "Current committed tick.", "id": "tick", "required": true, "units": "fixed-ticks", "value_type": "unsigned-integer" }, { "description": "Configured tick limit.", "id": "tick_limit", "required": true, "units": "fixed-ticks", "value_type": "unsigned-integer" } ], "id": "developer.runtime", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "query", "name": "Runtime diagnostics", "namespace": "developer", "owner": "sim.fixed-step-scheduler", "replacement": null, "side_effects": "none", "signature": "developer.runtime(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/developer.runtime.html" }, { "authority": "read_only", "availability": "runtime API 1", "deprecated": null, "description": "Detached runtime tuning definitions and current values.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Namespace lookup is constant-time and performs no owner work.", "examples": [ "-- Read values through world.query(\"developer.tuning.values\", request)." ], "history": [ "1.1.0: Runtime tuning inspection namespace added." ], "id": "developer.tuning", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [], "related": [ "developer.tuning.values", "restricted.tuning" ], "returns": "The documented runtime tuning query contracts available to the package.", "signature": "namespace developer.tuning", "usage": "Use developer.tuning to discover detached runtime tuning values. The namespace does not change state." }, "errors": [], "fields": [], "id": "developer.tuning", "introduced": { "display": "1.1.0", "major": 1, "minor": 1, "patch": 0 }, "kind": "namespace", "name": "Developer tuning", "namespace": "developer.tuning", "owner": "app.runtime-tuning", "replacement": null, "side_effects": "none", "signature": "namespace developer.tuning", "source_location": "src/app/script_api_catalog.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/developer.tuning.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns registered runtime tuning definitions and their current detached values.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "One bounded query and one owner visit per returned definition.", "examples": [ "local result = world.query(\"developer.tuning.values\", {page_size = 1, filters = {tuning_id = \"simulation.time-scale-basis-points\"}})" ], "history": [ "1.1.0: Runtime tuning inspection query added." ], "id": "developer.tuning.values", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [ "filters: optional tuning_id string.", "cursor: continuation cursor.", "page_size: bounded record limit." ], "related": [ "developer.tuning", "restricted.tuning.set-value", "events.tuning.changed", "world.query" ], "returns": "Detached tuning records. Returned values cannot mutate the runtime.", "signature": "developer.tuning.values(filters?, cursor?, page_size?) -> query-page", "usage": "Read registered tuning definitions, ranges, units, current values, and the owner revision. Filter by tuning_id when preparing a revision-checked change." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "When a committed change becomes effective.", "id": "change_policy", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Current tuning value.", "id": "current_value", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Default tuning value.", "id": "default_value", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Highest accepted tuning value.", "id": "maximum_value", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Lowest accepted tuning value.", "id": "minimum_value", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Current tuning-owner revision.", "id": "revision", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Runtime scope affected by the value.", "id": "scope", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Registered tuning identity.", "id": "tuning_id", "required": true, "units": null, "value_type": "string" }, { "description": "Unit used by the tuning value.", "id": "units", "required": true, "units": null, "value_type": "string" } ], "id": "developer.tuning.values", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "query", "name": "Runtime tuning values", "namespace": "developer.tuning", "owner": "app.runtime-tuning", "replacement": null, "side_effects": "none", "signature": "developer.tuning.values(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/developer.tuning.values.html" }, { "authority": "read_only", "availability": "runtime API 1", "deprecated": null, "description": "Stable script API error identities.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Namespace lookup is constant-time and performs no owner work.", "examples": [ "-- Access documented members through error.action-collision." ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "error", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "error.action-collision", "error.capability-unavailable", "error.command-budget-exhausted", "error.command-owner-rejected", "error.command-queue-full", "error.invalid-action", "error.invalid-command", "error.invalid-query" ], "returns": "A stable namespace table containing only the documented child symbols available to this package origin.", "signature": "namespace error", "usage": "Use error only to reach its registered child contracts. The namespace itself performs no query, mutation, lifecycle transition, or drawing." }, "errors": [], "fields": [], "id": "error", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "namespace", "name": "Error", "namespace": "error", "owner": "app.script-api-registry", "replacement": null, "side_effects": "none", "signature": "namespace error", "source_location": "src/app/script_api_catalog.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/error.html" }, { "authority": "read_only", "availability": "all script lifecycles", "deprecated": null, "description": "A logical action identity conflicts with another declaration.", "determinism": "Stable error identity; diagnostic prose is not API state.", "documentation": { "cost": "Constant-size contract lookup or bounded retained-record access.", "examples": [ "if result.error_id == \"error.action-collision\" then\n return\nend" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "error.action-collision", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "error", "ui.action.resource-counts.toggle" ], "returns": "A stable error identity suitable for equality checks and diagnostics.", "signature": "error.action-collision", "usage": "Compare the returned error ID to error.action-collision. Treat diagnostic text as human-readable context, not as a value to parse." }, "errors": [], "fields": [], "id": "error.action-collision", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "error", "name": "Action collision", "namespace": "error", "owner": "app.script-api-registry", "replacement": null, "side_effects": "none", "signature": "error.action-collision", "source_location": "src/app/script_api_catalog.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/error.action-collision.html" }, { "authority": "read_only", "availability": "all script lifecycles", "deprecated": null, "description": "The current runtime does not implement the requested capability.", "determinism": "Stable error identity; diagnostic prose is not API state.", "documentation": { "cost": "Constant-size contract lookup or bounded retained-record access.", "examples": [ "if result.error_id == \"error.capability-unavailable\" then\n return\nend" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "error.capability-unavailable", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "error", "developer.runtime", "world.actor.info", "world.actor.needs", "world.building.info", "world.construction.progress", "world.household.wealth", "world.job.info", "world.order.info" ], "returns": "A stable error identity suitable for equality checks and diagnostics.", "signature": "error.capability-unavailable", "usage": "Compare the returned error ID to error.capability-unavailable. Treat diagnostic text as human-readable context, not as a value to parse." }, "errors": [], "fields": [], "id": "error.capability-unavailable", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "error", "name": "Capability unavailable", "namespace": "error", "owner": "app.script-api-registry", "replacement": null, "side_effects": "none", "signature": "error.capability-unavailable", "source_location": "src/app/script_api_catalog.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/error.capability-unavailable.html" }, { "authority": "read_only", "availability": "all script lifecycles", "deprecated": null, "description": "The requested capacity limit is lower than observed owner use.", "determinism": "Stable error identity; diagnostic prose is not API state.", "documentation": { "cost": "No extra work.", "examples": [ "if receipt.error_id == \"error.capacity-limit-below-current-use\" then -- use current usage end" ], "history": [ "1.2.0: Below-current-use error added." ], "id": "error.capacity-limit-below-current-use", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [], "related": [ "restricted.capacity-policy.set-limit" ], "returns": "A stable failed-command error.", "signature": "error.capacity-limit-below-current-use", "usage": "Choose a limit at or above current use." }, "errors": [], "fields": [], "id": "error.capacity-limit-below-current-use", "introduced": { "display": "1.2.0", "major": 1, "minor": 2, "patch": 0 }, "kind": "error", "name": "Capacity limit below current use", "namespace": "error", "owner": "app.script-api-registry", "replacement": null, "side_effects": "none", "signature": "error.capacity-limit-below-current-use", "source_location": "src/app/script_api_catalog.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/error.capacity-limit-below-current-use.html" }, { "authority": "read_only", "availability": "all script lifecycles", "deprecated": null, "description": "The package exhausted its bounded command submissions.", "determinism": "Stable error identity; diagnostic prose is not API state.", "documentation": { "cost": "Constant-size contract lookup or bounded retained-record access.", "examples": [ "if result.error_id == \"error.command-budget-exhausted\" then\n return\nend" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "error.command-budget-exhausted", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "error", "command.actor.release-control", "command.actor.take-control", "command.submit", "restricted.actor.crisis-override", "restricted.command.submit" ], "returns": "A stable error identity suitable for equality checks and diagnostics.", "signature": "error.command-budget-exhausted", "usage": "Compare the returned error ID to error.command-budget-exhausted. Treat diagnostic text as human-readable context, not as a value to parse." }, "errors": [], "fields": [], "id": "error.command-budget-exhausted", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "error", "name": "Command budget exhausted", "namespace": "error", "owner": "app.script-api-registry", "replacement": null, "side_effects": "none", "signature": "error.command-budget-exhausted", "source_location": "src/app/script_api_catalog.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/error.command-budget-exhausted.html" }, { "authority": "read_only", "availability": "all script lifecycles", "deprecated": null, "description": "The authoritative gameplay owner rejected the validated request.", "determinism": "Stable error identity; diagnostic prose is not API state.", "documentation": { "cost": "Constant-size contract lookup or bounded retained-record access.", "examples": [ "if result.error_id == \"error.command-owner-rejected\" then\n return\nend" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "error.command-owner-rejected", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "error", "command.actor.release-control", "command.actor.take-control", "restricted.actor.crisis-override" ], "returns": "A stable error identity suitable for equality checks and diagnostics.", "signature": "error.command-owner-rejected", "usage": "Compare the returned error ID to error.command-owner-rejected. Treat diagnostic text as human-readable context, not as a value to parse." }, "errors": [], "fields": [], "id": "error.command-owner-rejected", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "error", "name": "Command owner rejected", "namespace": "error", "owner": "app.script-api-registry", "replacement": null, "side_effects": "none", "signature": "error.command-owner-rejected", "source_location": "src/app/script_api_catalog.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/error.command-owner-rejected.html" }, { "authority": "read_only", "availability": "all script lifecycles", "deprecated": null, "description": "The bounded command queue cannot accept another request.", "determinism": "Stable error identity; diagnostic prose is not API state.", "documentation": { "cost": "Constant-size contract lookup or bounded retained-record access.", "examples": [ "if result.error_id == \"error.command-queue-full\" then\n return\nend" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "error.command-queue-full", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "error", "command.actor.release-control", "command.actor.take-control", "restricted.actor.crisis-override" ], "returns": "A stable error identity suitable for equality checks and diagnostics.", "signature": "error.command-queue-full", "usage": "Compare the returned error ID to error.command-queue-full. Treat diagnostic text as human-readable context, not as a value to parse." }, "errors": [], "fields": [], "id": "error.command-queue-full", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "error", "name": "Command queue full", "namespace": "error", "owner": "app.script-api-registry", "replacement": null, "side_effects": "none", "signature": "error.command-queue-full", "source_location": "src/app/script_api_catalog.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/error.command-queue-full.html" }, { "authority": "read_only", "availability": "all script lifecycles", "deprecated": null, "description": "The calling package cannot change the requested indicator channel.", "determinism": "Stable error identity; diagnostic prose is not API state.", "documentation": { "cost": "Constant-time origin validation.", "examples": [ "-- Development-only channels reject standard-package mutation attempts." ], "history": [ "1.7.0: World-indicator channel authority error added." ], "id": "error.indicator-channel-authority", "manual_nodes": [ "phase.17", "engine-reference.extension-contract" ], "parameters": [], "related": [ "world_indicators.set-visible", "error.indicator-channel-unavailable" ], "returns": "A stable error identity with diagnostic detail; no channel state changes.", "signature": "error.indicator-channel-authority", "usage": "Handle an attempt by a package origin that is not authorized to change the requested indicator channel." }, "errors": [], "fields": [], "id": "error.indicator-channel-authority", "introduced": { "display": "1.7.0", "major": 1, "minor": 7, "patch": 0 }, "kind": "error", "name": "Indicator channel authority denied", "namespace": "error", "owner": "app.script-api-registry", "replacement": null, "side_effects": "none", "signature": "error.indicator-channel-authority", "source_location": "src/app/script_api_catalog.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/error.indicator-channel-authority.html" }, { "authority": "read_only", "availability": "all script lifecycles", "deprecated": null, "description": "The requested world-indicator channel is not registered or visible to the calling package origin.", "determinism": "Stable error identity; diagnostic prose is not API state.", "documentation": { "cost": "One bounded channel-registry lookup.", "examples": [ "-- Discover available channels before reading or changing visibility." ], "history": [ "1.7.0: World-indicator channel availability error added." ], "id": "error.indicator-channel-unavailable", "manual_nodes": [ "phase.17", "engine-reference.extension-contract" ], "parameters": [], "related": [ "world_indicators.channels", "world_indicators.is-visible", "world_indicators.set-visible" ], "returns": "A stable error identity with diagnostic detail; no channel state changes.", "signature": "error.indicator-channel-unavailable", "usage": "Handle an unknown channel identity or a registered channel that is not exposed to the calling package origin." }, "errors": [], "fields": [], "id": "error.indicator-channel-unavailable", "introduced": { "display": "1.7.0", "major": 1, "minor": 7, "patch": 0 }, "kind": "error", "name": "Indicator channel unavailable", "namespace": "error", "owner": "app.script-api-registry", "replacement": null, "side_effects": "none", "signature": "error.indicator-channel-unavailable", "source_location": "src/app/script_api_catalog.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/error.indicator-channel-unavailable.html" }, { "authority": "read_only", "availability": "all script lifecycles", "deprecated": null, "description": "The action identity is not declared by the calling package.", "determinism": "Stable error identity; diagnostic prose is not API state.", "documentation": { "cost": "Constant-size contract lookup or bounded retained-record access.", "examples": [ "if result.error_id == \"error.invalid-action\" then\n return\nend" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "error.invalid-action", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "error", "lifecycle.handle-action", "ui.action.actor.release-control", "ui.action.actor.take-control", "ui.action.composition-proof.crisis-override", "ui.action.composition-proof.take-control", "ui.action.composition-proof.use-alternate", "ui.action.composition-proof.use-standard" ], "returns": "A stable error identity suitable for equality checks and diagnostics.", "signature": "error.invalid-action", "usage": "Compare the returned error ID to error.invalid-action. Treat diagnostic text as human-readable context, not as a value to parse." }, "errors": [], "fields": [], "id": "error.invalid-action", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "error", "name": "Invalid action", "namespace": "error", "owner": "app.script-api-registry", "replacement": null, "side_effects": "none", "signature": "error.invalid-action", "source_location": "src/app/script_api_catalog.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/error.invalid-action.html" }, { "authority": "read_only", "availability": "all script lifecycles", "deprecated": null, "description": "The capacity-policy identity, value, or patch is invalid.", "determinism": "Stable error identity; diagnostic prose is not API state.", "documentation": { "cost": "No extra work.", "examples": [ "if receipt.error_id == \"error.invalid-capacity-policy\" then -- refresh end" ], "history": [ "1.2.0: Capacity-policy validation error added." ], "id": "error.invalid-capacity-policy", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [], "related": [ "restricted.capacity-policy.set-limit" ], "returns": "A stable failed-command error.", "signature": "error.invalid-capacity-policy", "usage": "Check the policy identity and technical range." }, "errors": [], "fields": [], "id": "error.invalid-capacity-policy", "introduced": { "display": "1.2.0", "major": 1, "minor": 2, "patch": 0 }, "kind": "error", "name": "Invalid capacity policy", "namespace": "error", "owner": "app.script-api-registry", "replacement": null, "side_effects": "none", "signature": "error.invalid-capacity-policy", "source_location": "src/app/script_api_catalog.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/error.invalid-capacity-policy.html" }, { "authority": "read_only", "availability": "all script lifecycles", "deprecated": null, "description": "The command identity or argument schema is invalid.", "determinism": "Stable error identity; diagnostic prose is not API state.", "documentation": { "cost": "Constant-size contract lookup or bounded retained-record access.", "examples": [ "if result.error_id == \"error.invalid-command\" then\n return\nend" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "error.invalid-command", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "error", "command.actor.release-control", "command.actor.take-control", "command.submit", "restricted.actor.crisis-override" ], "returns": "A stable error identity suitable for equality checks and diagnostics.", "signature": "error.invalid-command", "usage": "Compare the returned error ID to error.invalid-command. Treat diagnostic text as human-readable context, not as a value to parse." }, "errors": [], "fields": [], "id": "error.invalid-command", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "error", "name": "Invalid command", "namespace": "error", "owner": "app.script-api-registry", "replacement": null, "side_effects": "none", "signature": "error.invalid-command", "source_location": "src/app/script_api_catalog.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/error.invalid-command.html" }, { "authority": "read_only", "availability": "all script lifecycles", "deprecated": null, "description": "The query identity, filters, cursor, or page size is invalid.", "determinism": "Stable error identity; diagnostic prose is not API state.", "documentation": { "cost": "Constant-size contract lookup or bounded retained-record access.", "examples": [ "if result.error_id == \"error.invalid-query\" then\n return\nend" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "error.invalid-query", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "error", "developer.runtime", "world.actor.info", "world.actor.needs", "world.building.info", "world.construction.progress", "world.household.wealth", "world.job.info", "world.order.info" ], "returns": "A stable error identity suitable for equality checks and diagnostics.", "signature": "error.invalid-query", "usage": "Compare the returned error ID to error.invalid-query. Treat diagnostic text as human-readable context, not as a value to parse." }, "errors": [], "fields": [], "id": "error.invalid-query", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "error", "name": "Invalid query", "namespace": "error", "owner": "app.script-api-registry", "replacement": null, "side_effects": "none", "signature": "error.invalid-query", "source_location": "src/app/script_api_catalog.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/error.invalid-query.html" }, { "authority": "read_only", "availability": "all script lifecycles", "deprecated": null, "description": "The theme contract violates scale or accessibility constraints.", "determinism": "Stable error identity; diagnostic prose is not API state.", "documentation": { "cost": "Constant-size contract lookup or bounded retained-record access.", "examples": [ "if result.error_id == \"error.invalid-theme\" then\n return\nend" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "error.invalid-theme", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "error", "ui.set-theme" ], "returns": "A stable error identity suitable for equality checks and diagnostics.", "signature": "error.invalid-theme", "usage": "Compare the returned error ID to error.invalid-theme. Treat diagnostic text as human-readable context, not as a value to parse." }, "errors": [], "fields": [], "id": "error.invalid-theme", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "error", "name": "Invalid theme", "namespace": "error", "owner": "app.script-api-registry", "replacement": null, "side_effects": "none", "signature": "error.invalid-theme", "source_location": "src/app/script_api_catalog.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/error.invalid-theme.html" }, { "authority": "read_only", "availability": "all script lifecycles", "deprecated": null, "description": "The tuning identity, value, or patch is invalid.", "determinism": "Stable error identity; diagnostic prose is not API state.", "documentation": { "cost": "No extra work beyond rejected owner validation.", "examples": [ "if receipt.error_id == \"error.invalid-tuning\" then -- refresh the tuning record end" ], "history": [ "1.1.0: Runtime tuning validation error added." ], "id": "error.invalid-tuning", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [], "related": [ "restricted.tuning.set-value", "developer.tuning.values" ], "returns": "A stable error identity in a rejected or failed command receipt.", "signature": "error.invalid-tuning", "usage": "Handle this error by checking the registered ID, supported range, and whether the requested value actually differs from current state." }, "errors": [], "fields": [], "id": "error.invalid-tuning", "introduced": { "display": "1.1.0", "major": 1, "minor": 1, "patch": 0 }, "kind": "error", "name": "Invalid tuning", "namespace": "error", "owner": "app.script-api-registry", "replacement": null, "side_effects": "none", "signature": "error.invalid-tuning", "source_location": "src/app/script_api_catalog.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/error.invalid-tuning.html" }, { "authority": "read_only", "availability": "all script lifecycles", "deprecated": null, "description": "Candidate package validation or proof composition failed.", "determinism": "Stable error identity; diagnostic prose is not API state.", "documentation": { "cost": "Constant-size contract lookup or bounded retained-record access.", "examples": [ "if result.error_id == \"error.package-reload\" then\n return\nend" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "error.package-reload", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "error", "ui.action.packages.reload" ], "returns": "A stable error identity suitable for equality checks and diagnostics.", "signature": "error.package-reload", "usage": "Compare the returned error ID to error.package-reload. Treat diagnostic text as human-readable context, not as a value to parse." }, "errors": [], "fields": [], "id": "error.package-reload", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "error", "name": "Package reload failed", "namespace": "error", "owner": "app.script-api-registry", "replacement": null, "side_effects": "none", "signature": "error.package-reload", "source_location": "src/app/script_api_catalog.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/error.package-reload.html" }, { "authority": "read_only", "availability": "all script lifecycles", "deprecated": null, "description": "The package exhausted query, record, or owner-visit work.", "determinism": "Stable error identity; diagnostic prose is not API state.", "documentation": { "cost": "Constant-size contract lookup or bounded retained-record access.", "examples": [ "if result.error_id == \"error.query-budget-exhausted\" then\n return\nend" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "error.query-budget-exhausted", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "error", "developer.runtime", "world.actor.info", "world.actor.needs", "world.building.info", "world.construction.progress", "world.household.wealth", "world.job.info", "world.order.info" ], "returns": "A stable error identity suitable for equality checks and diagnostics.", "signature": "error.query-budget-exhausted", "usage": "Compare the returned error ID to error.query-budget-exhausted. Treat diagnostic text as human-readable context, not as a value to parse." }, "errors": [], "fields": [], "id": "error.query-budget-exhausted", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "error", "name": "Query budget exhausted", "namespace": "error", "owner": "app.script-api-registry", "replacement": null, "side_effects": "none", "signature": "error.query-budget-exhausted", "source_location": "src/app/script_api_catalog.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/error.query-budget-exhausted.html" }, { "authority": "read_only", "availability": "all script lifecycles", "deprecated": null, "description": "Returned owner data does not match the registered detached schema.", "determinism": "Stable error identity; diagnostic prose is not API state.", "documentation": { "cost": "Constant-size contract lookup or bounded retained-record access.", "examples": [ "if result.error_id == \"error.query-contract-violation\" then\n return\nend" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "error.query-contract-violation", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "error", "developer.runtime", "world.actor.info", "world.actor.needs", "world.building.info", "world.construction.progress", "world.household.wealth", "world.job.info", "world.order.info" ], "returns": "A stable error identity suitable for equality checks and diagnostics.", "signature": "error.query-contract-violation", "usage": "Compare the returned error ID to error.query-contract-violation. Treat diagnostic text as human-readable context, not as a value to parse." }, "errors": [], "fields": [], "id": "error.query-contract-violation", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "error", "name": "Query contract violation", "namespace": "error", "owner": "app.script-api-registry", "replacement": null, "side_effects": "none", "signature": "error.query-contract-violation", "source_location": "src/app/script_api_catalog.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/error.query-contract-violation.html" }, { "authority": "read_only", "availability": "all script lifecycles", "deprecated": null, "description": "The caller does not have a host-created development origin.", "determinism": "Stable error identity; diagnostic prose is not API state.", "documentation": { "cost": "Constant-size contract lookup or bounded retained-record access.", "examples": [ "if result.error_id == \"error.restricted-command\" then\n return\nend" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "error.restricted-command", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "error", "command.actor.release-control", "command.actor.take-control", "restricted.actor.crisis-override", "restricted.command.submit" ], "returns": "A stable error identity suitable for equality checks and diagnostics.", "signature": "error.restricted-command", "usage": "Compare the returned error ID to error.restricted-command. Treat diagnostic text as human-readable context, not as a value to parse." }, "errors": [], "fields": [], "id": "error.restricted-command", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "error", "name": "Restricted command denied", "namespace": "error", "owner": "app.script-api-registry", "replacement": null, "side_effects": "none", "signature": "error.restricted-command", "source_location": "src/app/script_api_catalog.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/error.restricted-command.html" }, { "authority": "read_only", "availability": "all script lifecycles", "deprecated": null, "description": "The capacity-policy owner changed after the caller captured its revision.", "determinism": "Stable error identity; diagnostic prose is not API state.", "documentation": { "cost": "No extra work.", "examples": [ "if receipt.error_id == \"error.stale-capacity-policy\" then -- refresh end" ], "history": [ "1.2.0: Stale capacity-policy error added." ], "id": "error.stale-capacity-policy", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [], "related": [ "restricted.capacity-policy.set-limit" ], "returns": "A stable failed-command error.", "signature": "error.stale-capacity-policy", "usage": "Refresh the policy before resubmitting." }, "errors": [], "fields": [], "id": "error.stale-capacity-policy", "introduced": { "display": "1.2.0", "major": 1, "minor": 2, "patch": 0 }, "kind": "error", "name": "Stale capacity-policy revision", "namespace": "error", "owner": "app.script-api-registry", "replacement": null, "side_effects": "none", "signature": "error.stale-capacity-policy", "source_location": "src/app/script_api_catalog.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/error.stale-capacity-policy.html" }, { "authority": "read_only", "availability": "all script lifecycles", "deprecated": null, "description": "The tuning owner changed after the caller captured its revision.", "determinism": "Stable error identity; diagnostic prose is not API state.", "documentation": { "cost": "No extra work beyond rejected owner validation.", "examples": [ "if receipt.error_id == \"error.stale-tuning\" then -- query the latest revision end" ], "history": [ "1.1.0: Stale runtime tuning revision error added." ], "id": "error.stale-tuning", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [], "related": [ "restricted.tuning.set-value", "developer.tuning.values" ], "returns": "A stable error identity when expected_revision no longer matches.", "signature": "error.stale-tuning", "usage": "Refresh developer.tuning.values and decide whether the requested change still applies before resubmitting." }, "errors": [], "fields": [], "id": "error.stale-tuning", "introduced": { "display": "1.1.0", "major": 1, "minor": 1, "patch": 0 }, "kind": "error", "name": "Stale tuning revision", "namespace": "error", "owner": "app.script-api-registry", "replacement": null, "side_effects": "none", "signature": "error.stale-tuning", "source_location": "src/app/script_api_catalog.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/error.stale-tuning.html" }, { "authority": "read_only", "availability": "all script lifecycles", "deprecated": null, "description": "Providers or contributions cannot resolve one valid composition.", "determinism": "Stable error identity; diagnostic prose is not API state.", "documentation": { "cost": "Constant-size contract lookup or bounded retained-record access.", "examples": [ "if result.error_id == \"error.ui-composition-conflict\" then\n return\nend" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "error.ui-composition-conflict", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "error", "ui.select-provider", "ui.slot.player-hud.panels", "ui.slot.player-hud.toolbar", "ui.slot.recovery.status", "ui.surface.player-hud", "ui.surface.recovery" ], "returns": "A stable error identity suitable for equality checks and diagnostics.", "signature": "error.ui-composition-conflict", "usage": "Compare the returned error ID to error.ui-composition-conflict. Treat diagnostic text as human-readable context, not as a value to parse." }, "errors": [], "fields": [], "id": "error.ui-composition-conflict", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "error", "name": "Interface composition conflict", "namespace": "error", "owner": "app.script-api-registry", "replacement": null, "side_effects": "none", "signature": "error.ui-composition-conflict", "source_location": "src/app/script_api_catalog.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/error.ui-composition-conflict.html" }, { "authority": "read_only", "availability": "runtime API 1", "deprecated": null, "description": "Immutable facts published after committed mutation.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Namespace lookup is constant-time and performs no owner work.", "examples": [ "-- Access documented members through events.listen." ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "events", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "events.after", "events.ignore", "events.listen" ], "returns": "A stable namespace table containing only the documented child symbols available to this package origin.", "signature": "namespace events", "usage": "Use events only to reach its registered child contracts. The namespace itself performs no query, mutation, lifecycle transition, or drawing." }, "errors": [], "fields": [], "id": "events", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "namespace", "name": "Events", "namespace": "events", "owner": "app.script-command-service", "replacement": null, "side_effects": "none", "signature": "namespace events", "source_location": "src/app/script_api_catalog.cpp", "timing": "post_commit", "units": null, "url": "/api/v1/symbols/events.html" }, { "authority": "read_only", "availability": "Phase 14 package callbacks", "deprecated": null, "description": "Returns bounded post-commit events after a sequence.", "determinism": "Host-created package identity and per-callback budgets.", "documentation": { "cost": "Constant-size contract lookup or bounded retained-record access.", "examples": [ "local events_since_last_frame = events.after(last_sequence, 8)" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "events.after", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [ "sequence: last consumed event sequence; use 0 to begin at retained history.", "maximum_count: positive result limit capped by the host." ], "related": [ "events", "events.command.completed", "command.receipt" ], "returns": "A stable sequence-ordered array of retained post-commit events after the supplied sequence.", "signature": "events.after(sequence, maximum_count) -> event[]", "usage": "Read a bounded post-commit event page after the last sequence already processed by the package." }, "errors": [], "fields": [], "id": "events.after", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "function", "name": "after", "namespace": "events", "owner": "app.ScriptPackageHost", "replacement": null, "side_effects": "none", "signature": "events.after(sequence, maximum_count) -> event[]", "source_location": "src/app/script_package_host.cpp", "timing": "post_commit", "units": null, "url": "/api/v1/symbols/events.after.html" }, { "authority": "read_only", "availability": "runtime API 1", "deprecated": null, "description": "Post-commit facts produced by scenario capacity-policy changes.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Delivery uses bounded event budgets.", "examples": [ "-- Subscribe through events.listen." ], "history": [ "1.2.0: Capacity-policy event namespace added." ], "id": "events.capacity-policy", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [], "related": [ "events.capacity-policy.changed" ], "returns": "The capacity-policy event contracts.", "signature": "namespace events.capacity-policy", "usage": "Observe facts published after capacity-policy commits." }, "errors": [], "fields": [], "id": "events.capacity-policy", "introduced": { "display": "1.2.0", "major": 1, "minor": 2, "patch": 0 }, "kind": "namespace", "name": "Capacity-policy events", "namespace": "events.capacity-policy", "owner": "app.scenario-capacity-policy", "replacement": null, "side_effects": "none", "signature": "namespace events.capacity-policy", "source_location": "src/app/script_api_catalog.cpp", "timing": "post_commit", "units": null, "url": "/api/v1/symbols/events.capacity-policy.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Reports one scenario capacity limit only after the policy owner commits it.", "determinism": "ordered after the capacity-policy commit and before command completion", "documentation": { "cost": "One retained event and callback delivery.", "examples": [ "local subscription = events.listen(\"events.capacity-policy.changed\", function(event) print(event.payload.current_limit) end)" ], "history": [ "1.2.0: Capacity-policy event added." ], "id": "events.capacity-policy.changed", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [ "policy_id: changed identity.", "previous_limit: prior value.", "current_limit: committed value.", "current_usage: observed use.", "revision: new revision.", "origin_id: caller identity.", "request_sequence: command sequence." ], "related": [ "developer.capacity-policy.current", "restricted.capacity-policy.set-limit" ], "returns": "An immutable post-commit event.", "signature": "events.capacity-policy.changed(policy_id, previous_limit, current_limit, current_usage, revision, origin_id, request_sequence)", "usage": "Refresh displayed capacity values after a committed change." }, "errors": [], "fields": [ { "description": "Committed capacity limit.", "id": "current_limit", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Observed owner use when the limit committed.", "id": "current_usage", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Engine-created caller origin ID.", "id": "origin_id", "required": true, "units": null, "value_type": "string" }, { "description": "Registered scenario capacity-policy identity.", "id": "policy_id", "required": true, "units": null, "value_type": "string" }, { "description": "Limit before the committed change.", "id": "previous_limit", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Command request that produced the change.", "id": "request_sequence", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Scenario capacity-policy revision after the commit.", "id": "revision", "required": true, "units": null, "value_type": "revision" } ], "id": "events.capacity-policy.changed", "introduced": { "display": "1.2.0", "major": 1, "minor": 2, "patch": 0 }, "kind": "event", "name": "Capacity policy changed", "namespace": "events.capacity-policy", "owner": "app.scenario-capacity-policy", "replacement": null, "side_effects": "none", "signature": "events.capacity-policy.changed(policy_id, previous_limit, current_limit, current_usage, revision, origin_id, request_sequence)", "source_location": "src/app/script_event_service.cpp", "timing": "post_commit", "units": null, "url": "/api/v1/symbols/events.capacity-policy.changed.html" }, { "authority": "read_only", "availability": "runtime API 1", "deprecated": null, "description": "Post-commit facts produced by typed command execution.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Namespace lookup is constant-time and performs no owner work.", "examples": [ "-- Access documented members through events.command.completed." ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "events.command", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "events.command.completed" ], "returns": "A stable namespace table containing only the documented child symbols available to this package origin.", "signature": "namespace events.command", "usage": "Use events.command only to reach its registered child contracts. The namespace itself performs no query, mutation, lifecycle transition, or drawing." }, "errors": [], "fields": [], "id": "events.command", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "namespace", "name": "Command events", "namespace": "events.command", "owner": "app.script-command-service", "replacement": null, "side_effects": "none", "signature": "namespace events.command", "source_location": "src/app/script_api_catalog.cpp", "timing": "post_commit", "units": null, "url": "/api/v1/symbols/events.command.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Reports a typed command only after its owner commits successfully.", "determinism": "ordered by event publication sequence and committed tick", "documentation": { "cost": "Counts against the package active-delivery and protected-callback budgets.", "examples": [ "events.listen(\"events.command.completed\", function(event)\n feedback = event.payload.command_id .. \" completed\"\nend)" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "events.command.completed", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "events.command", "events.listen", "events.after", "command.receipt" ], "returns": "A fresh detached callback-local table containing the immutable post-commit fact. Editing the table cannot change the source event or another callback's copy.", "signature": "events.command.completed(request_sequence, command_id, origin_id, target_tick)", "usage": "Listen for events.command.completed after authoritative mutation commits. Use events.after only for explicit catch-up or diagnostic recovery." }, "errors": [], "fields": [ { "description": "Stable command symbol ID.", "id": "command_id", "required": true, "units": null, "value_type": "string" }, { "description": "Engine-created caller origin ID.", "id": "origin_id", "required": true, "units": null, "value_type": "string" }, { "description": "Completed command request sequence.", "id": "request_sequence", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Requested fixed simulation tick.", "id": "target_tick", "required": true, "units": "simulation-ticks", "value_type": "tick" } ], "id": "events.command.completed", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "event", "name": "Command completed", "namespace": "events.command", "owner": "app.script-event-service", "replacement": null, "side_effects": "none", "signature": "events.command.completed(request_sequence, command_id, origin_id, target_tick)", "source_location": "src/app/script_event_service.cpp", "timing": "post_commit", "units": null, "url": "/api/v1/symbols/events.command.completed.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Reports a typed command after its gameplay owner rejects the fixed-tick request.", "determinism": "ordered by event publication sequence and committed tick", "documentation": { "cost": "One bounded retained event and one callback delivery per subscribed package.", "examples": [ "local subscription = events.listen(\"events.command.failed\", function(event)\n ui.text(\"Command\", event.payload.detail)\nend)" ], "history": [ "1.3.0: Owner-rejected command feedback event added for Phase 16D." ], "id": "events.command.failed", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [ "request_sequence: rejected command request.", "command_id: stable command identity.", "origin_id: engine-created caller identity.", "target_tick: requested fixed tick.", "error_id: stable rejection identity.", "detail: player-readable owner explanation." ], "related": [ "events.command.completed", "events.listen", "command.submit" ], "returns": "An immutable event published after the gameplay owner rejects the request without mutation.", "signature": "events.command.failed(request_sequence, command_id, origin_id, target_tick, error_id, detail)", "usage": "Listen for fixed-tick command requests that reached their gameplay owner but were rejected. Display detail to the player and use error_id for stable recovery logic." }, "errors": [], "fields": [ { "description": "Stable command symbol ID.", "id": "command_id", "required": true, "units": null, "value_type": "string" }, { "description": "Player-readable owner rejection detail.", "id": "detail", "required": true, "units": null, "value_type": "string" }, { "description": "Stable rejection reason ID.", "id": "error_id", "required": true, "units": null, "value_type": "string" }, { "description": "Engine-created caller origin ID.", "id": "origin_id", "required": true, "units": null, "value_type": "string" }, { "description": "Rejected command request sequence.", "id": "request_sequence", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Requested fixed simulation tick.", "id": "target_tick", "required": true, "units": "simulation-ticks", "value_type": "tick" } ], "id": "events.command.failed", "introduced": { "display": "1.3.0", "major": 1, "minor": 3, "patch": 0 }, "kind": "event", "name": "Command failed", "namespace": "events.command", "owner": "app.script-event-service", "replacement": null, "side_effects": "none", "signature": "events.command.failed(request_sequence, command_id, origin_id, target_tick, error_id, detail)", "source_location": "src/app/script_event_service.cpp", "timing": "post_commit", "units": null, "url": "/api/v1/symbols/events.command.failed.html" }, { "authority": "read_only", "availability": "Phase 14 package callbacks", "deprecated": null, "description": "Removes one generation-scoped event subscription created by this package.", "determinism": "Host-created package identity and per-callback budgets.", "documentation": { "cost": "Bounded by the package subscription limit. Removal during delivery takes effect before the next event and releases the callback after the current protected call.", "examples": [ "local subscription = events.listen(\"events.command.completed\", on_completed)\n-- Later in the same package generation:\nevents.ignore(subscription)" ], "history": [ "1.0.0: Active generation-scoped event delivery added in Phase 14M." ], "id": "events.ignore", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [ "subscription_id: positive opaque ID returned by events.listen in the current package generation." ], "related": [ "events", "events.listen", "events.command.completed" ], "returns": "True when the current package owned and removed the subscription; otherwise false.", "signature": "events.ignore(subscription_id) -> removed", "usage": "Remove a subscription created by the current package generation. Calling it again or passing an expired ID returns false without affecting another package." }, "errors": [], "fields": [], "id": "events.ignore", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "function", "name": "ignore", "namespace": "events", "owner": "app.ScriptPackageHost", "replacement": null, "side_effects": "none", "signature": "events.ignore(subscription_id) -> removed", "source_location": "src/app/script_package_host.cpp", "timing": "post_commit", "units": null, "url": "/api/v1/symbols/events.ignore.html" }, { "authority": "read_only", "availability": "Phase 14 package callbacks", "deprecated": null, "description": "Registers a generation-scoped callback for one typed post-commit event.", "determinism": "Host-created package identity and per-callback budgets.", "documentation": { "cost": "At most 64 subscriptions and 64 active deliveries per package dispatch. Source history retains at most 256 events; overflow is diagnosed and bounded.", "examples": [ "local subscription = events.listen(\n \"events.command.completed\",\n function(event)\n feedback = event.payload.command_id .. \" completed\"\n end\n)" ], "history": [ "1.0.0: Active generation-scoped event delivery added in Phase 14M." ], "id": "events.listen", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [ "event_id: stable ID of a registered event.", "callback: Lua function receiving one fresh detached callback-local event table." ], "related": [ "events", "events.ignore", "events.after", "events.command.completed", "command.submit" ], "returns": "A positive opaque subscription ID scoped to the current package and Lua generation.", "signature": "events.listen(event_id, callback) -> subscription_id", "usage": "Register one Lua function for a documented typed event. The host invokes it after authoritative commit at a safe frame boundary and destroys the subscription with the Lua generation." }, "errors": [], "fields": [], "id": "events.listen", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "function", "name": "listen", "namespace": "events", "owner": "app.ScriptPackageHost", "replacement": null, "side_effects": "none", "signature": "events.listen(event_id, callback) -> subscription_id", "source_location": "src/app/script_package_host.cpp", "timing": "post_commit", "units": null, "url": "/api/v1/symbols/events.listen.html" }, { "authority": "read_only", "availability": "runtime API 1", "deprecated": null, "description": "Post-commit facts produced by conserved currency transfers.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Namespace lookup is constant-time and performs no owner work.", "examples": [ "-- Listen through events.money.transferred." ], "history": [ "1.4.0: Post-commit money event namespace added for Phase 16D2." ], "id": "events.money", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [], "related": [ "events.money.transferred", "events.listen" ], "returns": "The documented money event contracts available to the package.", "signature": "namespace events.money", "usage": "Use events.money to listen for immutable facts produced after Resource commits a money transfer." }, "errors": [], "fields": [], "id": "events.money", "introduced": { "display": "1.4.0", "major": 1, "minor": 4, "patch": 0 }, "kind": "namespace", "name": "Money events", "namespace": "events.money", "owner": "game.resource-economy", "replacement": null, "side_effects": "none", "signature": "namespace events.money", "source_location": "src/app/script_api_catalog.cpp", "timing": "post_commit", "units": null, "url": "/api/v1/symbols/events.money.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Reports a conserved currency transfer only after Resource commits both custody changes.", "determinism": "ordered after the Resource commit and before command completion", "documentation": { "cost": "One bounded retained event and one callback delivery per subscribed package.", "examples": [ "events.listen(\"events.money.transferred\", function(event)\n ui.text(\"Contribution\", tostring(event.payload.amount_minor_units))\nend)" ], "history": [ "1.4.0: Conserved transfer fact added for Phase 16D2." ], "id": "events.money.transferred", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [ "transfer_id: Resource-owned transfer identity.", "actor_id: source Actor.", "household_id: destination Household.", "currency_definition_id: authored currency identity.", "resource_id: runtime Resource identity.", "amount_minor_units: exact transferred amount.", "personal_balance: resulting wallet balance.", "household_balance: resulting Household balance.", "origin_id: engine-created caller identity.", "request_sequence: originating command request." ], "related": [ "command.money.contribute", "events.listen", "world.actor.wealth", "world.household.wealth" ], "returns": "An immutable event published after both custody quantities and transfer history commit.", "signature": "events.money.transferred(transfer_id, actor_id, household_id, currency_definition_id, resource_id, amount_minor_units, personal_balance, household_balance, origin_id, request_sequence)", "usage": "Listen for completed money transfers. Treat the payload as a detached fact; query again when preparing a later revision-checked command." }, "errors": [], "fields": [ { "description": "Actor whose personal custody supplied the transfer.", "id": "actor_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Exact amount transferred.", "id": "amount_minor_units", "required": true, "units": "minor-currency-units", "value_type": "unsigned-integer" }, { "description": "Authored currency definition identity.", "id": "currency_definition_id", "required": true, "units": null, "value_type": "string" }, { "description": "Household-money balance after the commit.", "id": "household_balance", "required": true, "units": "minor-currency-units", "value_type": "unsigned-integer" }, { "description": "Actor household that received the contribution.", "id": "household_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Engine-created caller origin ID.", "id": "origin_id", "required": true, "units": null, "value_type": "string" }, { "description": "Actor-wallet balance after the commit.", "id": "personal_balance", "required": true, "units": "minor-currency-units", "value_type": "unsigned-integer" }, { "description": "Command request that produced the transfer.", "id": "request_sequence", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Runtime Resource identity.", "id": "resource_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Resource-owned custody-transfer identity.", "id": "transfer_id", "required": true, "units": null, "value_type": "stable-id" } ], "id": "events.money.transferred", "introduced": { "display": "1.4.0", "major": 1, "minor": 4, "patch": 0 }, "kind": "event", "name": "Money transferred", "namespace": "events.money", "owner": "game.resource-economy", "replacement": null, "side_effects": "none", "signature": "events.money.transferred(transfer_id, actor_id, household_id, currency_definition_id, resource_id, amount_minor_units, personal_balance, household_balance, origin_id, request_sequence)", "source_location": "src/app/script_event_service.cpp", "timing": "post_commit", "units": "minor-currency-units", "url": "/api/v1/symbols/events.money.transferred.html" }, { "authority": "read_only", "availability": "runtime API 1", "deprecated": null, "description": "Post-commit facts produced by runtime tuning changes.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Namespace lookup is constant-time; delivery uses bounded package event budgets.", "examples": [ "-- Subscribe through events.listen(\"events.tuning.changed\", callback)." ], "history": [ "1.1.0: Runtime tuning event namespace added." ], "id": "events.tuning", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [], "related": [ "events.tuning.changed", "events.listen" ], "returns": "The documented post-commit tuning event contracts.", "signature": "namespace events.tuning", "usage": "Use events.tuning to observe immutable facts published after the runtime tuning owner commits." }, "errors": [], "fields": [], "id": "events.tuning", "introduced": { "display": "1.1.0", "major": 1, "minor": 1, "patch": 0 }, "kind": "namespace", "name": "Tuning events", "namespace": "events.tuning", "owner": "app.runtime-tuning", "replacement": null, "side_effects": "none", "signature": "namespace events.tuning", "source_location": "src/app/script_api_catalog.cpp", "timing": "post_commit", "units": null, "url": "/api/v1/symbols/events.tuning.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Reports one runtime tuning value only after the tuning owner commits it.", "determinism": "ordered after the tuning commit and before command completion", "documentation": { "cost": "One bounded retained event and one callback delivery per subscribed package.", "examples": [ "local subscription = events.listen(\"events.tuning.changed\", function(event) print(event.payload.current_value) end)" ], "history": [ "1.1.0: Post-commit runtime tuning event added." ], "id": "events.tuning.changed", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [ "tuning_id: changed tuning identity.", "previous_value: value before commit.", "current_value: committed value.", "revision: new owner revision.", "origin_id: engine-created caller identity.", "request_sequence: originating command sequence." ], "related": [ "developer.tuning.values", "restricted.tuning.set-value", "events.listen", "events.after" ], "returns": "An immutable post-commit event payload.", "signature": "events.tuning.changed(tuning_id, previous_value, current_value, revision, origin_id, request_sequence)", "usage": "Listen for committed tuning changes and refresh any displayed values from the detached query when needed." }, "errors": [], "fields": [ { "description": "Committed tuning value.", "id": "current_value", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Engine-created caller origin ID.", "id": "origin_id", "required": true, "units": null, "value_type": "string" }, { "description": "Value before the committed change.", "id": "previous_value", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Command request that produced the change.", "id": "request_sequence", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Runtime tuning revision after the commit.", "id": "revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Registered runtime tuning identity.", "id": "tuning_id", "required": true, "units": null, "value_type": "string" } ], "id": "events.tuning.changed", "introduced": { "display": "1.1.0", "major": 1, "minor": 1, "patch": 0 }, "kind": "event", "name": "Tuning changed", "namespace": "events.tuning", "owner": "app.runtime-tuning", "replacement": null, "side_effects": "none", "signature": "events.tuning.changed(tuning_id, previous_value, current_value, revision, origin_id, request_sequence)", "source_location": "src/app/script_event_service.cpp", "timing": "post_commit", "units": null, "url": "/api/v1/symbols/events.tuning.changed.html" }, { "authority": "host_lifecycle", "availability": "runtime API 1", "deprecated": null, "description": "Host-dispatched package lifecycle callbacks.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Runs only at a bounded package lifecycle transition under host instruction and memory limits.", "examples": [ "-- Access documented members through lifecycle.handle-action." ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "lifecycle", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "lifecycle.handle-action", "lifecycle.initialize", "lifecycle.shutdown", "lifecycle.suspend", "lifecycle.validate" ], "returns": "A stable namespace table containing only the documented child symbols available to this package origin.", "signature": "namespace lifecycle", "usage": "Use lifecycle only to reach its registered child contracts. The namespace itself performs no query, mutation, lifecycle transition, or drawing." }, "errors": [], "fields": [], "id": "lifecycle", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "namespace", "name": "Lifecycle", "namespace": "lifecycle", "owner": "app.ScriptPackageHost", "replacement": null, "side_effects": "none", "signature": "namespace lifecycle", "source_location": "src/app/script_api_catalog.cpp", "timing": "lifecycle", "units": null, "url": "/api/v1/symbols/lifecycle.html" }, { "authority": "host_lifecycle", "availability": "Phase 14H standard interface", "deprecated": null, "description": "Receives one activated logical action and an optional selected list row ID.", "determinism": "Delivered in host activation order with a fresh callback budget.", "documentation": { "cost": "Constant-size contract lookup or bounded retained-record access.", "examples": [ "function handle_action(action_id, row_id)\n if action_id == \"ui.action.work.select\" then\n selected_work_row_id = row_id\n end\nend" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry.", "1.19.0: Added the optional stable list row identity." ], "id": "lifecycle.handle-action", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [ "action_id: stable ID emitted by a composed UI control.", "row_id: optional stable row identity emitted by ui.list." ], "related": [ "lifecycle", "error.invalid-action", "ui.action", "ui.button", "ui.list" ], "returns": "No engine-owned gameplay value. Success or a Lua error determines whether the lifecycle transition commits.", "signature": "handle_action(action_id, row_id?)", "usage": "Declare and implement lifecycle.handle-action through the package manifest lifecycle table. List activations provide the selected stable row ID as the optional second argument; button handlers remain compatible with a single action argument." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "lifecycle.handle-action", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "lifecycle", "name": "handle_action", "namespace": "lifecycle", "owner": "app.ScriptPackageHost", "replacement": null, "side_effects": "May submit documented commands through the existing command API.", "signature": "handle_action(action_id, row_id?)", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/lifecycle.handle-action.html" }, { "authority": "host_lifecycle", "availability": "Phase 14E package manifests", "deprecated": null, "description": "Host-dispatched bounded package lifecycle callback.", "determinism": "Dependency order; shutdown and suspension use reverse order.", "documentation": { "cost": "Runs only at a bounded package lifecycle transition under host instruction and memory limits.", "examples": [ "function initialize_package()\n -- Perform bounded package initialize work.\nend" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "lifecycle.initialize", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "lifecycle" ], "returns": "No engine-owned gameplay value. Success or a Lua error determines whether the lifecycle transition commits.", "signature": "initialize()", "usage": "Declare and implement lifecycle.initialize through the package manifest lifecycle table. Keep the callback bounded and use only the API capabilities available at that transition." }, "errors": [], "fields": [], "id": "lifecycle.initialize", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "lifecycle", "name": "initialize", "namespace": "lifecycle", "owner": "app.ScriptPackageHost", "replacement": null, "side_effects": "Lifecycle callbacks cannot submit gameplay commands.", "signature": "initialize()", "source_location": "src/app/script_package_host.cpp", "timing": "lifecycle", "units": null, "url": "/api/v1/symbols/lifecycle.initialize.html" }, { "authority": "host_lifecycle", "availability": "Phase 14E package manifests", "deprecated": null, "description": "Host-dispatched bounded package lifecycle callback.", "determinism": "Dependency order; shutdown and suspension use reverse order.", "documentation": { "cost": "Runs only at a bounded package lifecycle transition under host instruction and memory limits.", "examples": [ "function shutdown_package()\n -- Perform bounded package shutdown work.\nend" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "lifecycle.shutdown", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "lifecycle" ], "returns": "No engine-owned gameplay value. Success or a Lua error determines whether the lifecycle transition commits.", "signature": "shutdown()", "usage": "Declare and implement lifecycle.shutdown through the package manifest lifecycle table. Keep the callback bounded and use only the API capabilities available at that transition." }, "errors": [], "fields": [], "id": "lifecycle.shutdown", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "lifecycle", "name": "shutdown", "namespace": "lifecycle", "owner": "app.ScriptPackageHost", "replacement": null, "side_effects": "Lifecycle callbacks cannot submit gameplay commands.", "signature": "shutdown()", "source_location": "src/app/script_package_host.cpp", "timing": "lifecycle", "units": null, "url": "/api/v1/symbols/lifecycle.shutdown.html" }, { "authority": "host_lifecycle", "availability": "Phase 14E package manifests", "deprecated": null, "description": "Host-dispatched bounded package lifecycle callback.", "determinism": "Dependency order; shutdown and suspension use reverse order.", "documentation": { "cost": "Runs only at a bounded package lifecycle transition under host instruction and memory limits.", "examples": [ "function suspend_package()\n -- Perform bounded package suspend work.\nend" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "lifecycle.suspend", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "lifecycle" ], "returns": "No engine-owned gameplay value. Success or a Lua error determines whether the lifecycle transition commits.", "signature": "suspend()", "usage": "Declare and implement lifecycle.suspend through the package manifest lifecycle table. Keep the callback bounded and use only the API capabilities available at that transition." }, "errors": [], "fields": [], "id": "lifecycle.suspend", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "lifecycle", "name": "suspend", "namespace": "lifecycle", "owner": "app.ScriptPackageHost", "replacement": null, "side_effects": "Lifecycle callbacks cannot submit gameplay commands.", "signature": "suspend()", "source_location": "src/app/script_package_host.cpp", "timing": "lifecycle", "units": null, "url": "/api/v1/symbols/lifecycle.suspend.html" }, { "authority": "host_lifecycle", "availability": "Phase 14E package manifests", "deprecated": null, "description": "Host-dispatched bounded package lifecycle callback.", "determinism": "Dependency order; shutdown and suspension use reverse order.", "documentation": { "cost": "Runs only at a bounded package lifecycle transition under host instruction and memory limits.", "examples": [ "function validate_package()\n -- Perform bounded package validate work.\nend" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "lifecycle.validate", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "lifecycle" ], "returns": "No engine-owned gameplay value. Success or a Lua error determines whether the lifecycle transition commits.", "signature": "validate()", "usage": "Declare and implement lifecycle.validate through the package manifest lifecycle table. Keep the callback bounded and use only the API capabilities available at that transition." }, "errors": [], "fields": [], "id": "lifecycle.validate", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "lifecycle", "name": "validate", "namespace": "lifecycle", "owner": "app.ScriptPackageHost", "replacement": null, "side_effects": "Lifecycle callbacks cannot submit gameplay commands.", "signature": "validate()", "source_location": "src/app/script_package_host.cpp", "timing": "lifecycle", "units": null, "url": "/api/v1/symbols/lifecycle.validate.html" }, { "authority": "host_lifecycle", "availability": "runtime API 1", "deprecated": null, "description": "Host-controlled bounded performance logging for packages.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Namespace lookup is constant-time and performs no sampling.", "examples": [ "local session_id = performance.start_logging(3600)" ], "history": [ "1.0.0: Package-controlled bounded performance logging added during Phase 15 closure." ], "id": "performance", "manual_nodes": [ "phase.15", "engine-reference.extension-contract" ], "parameters": [], "related": [ "performance.start-logging", "performance.stop-logging", "developer.performance" ], "returns": "A stable namespace table containing logging lifecycle functions.", "signature": "namespace performance", "usage": "Use performance only to start or stop the host-wide bounded performance log. Read measurements through developer.performance queries." }, "errors": [], "fields": [], "id": "performance", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "namespace", "name": "Performance logging", "namespace": "performance", "owner": "app.runtime-performance-monitor", "replacement": null, "side_effects": "none", "signature": "namespace performance", "source_location": "src/app/script_api_catalog.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/performance.html" }, { "authority": "host_lifecycle", "availability": "Phase 14 package callbacks", "deprecated": null, "description": "Starts one bounded host-wide performance log owned by the calling package.", "determinism": "Host-created package identity and per-callback budgets.", "documentation": { "cost": "Reserves bounded sample storage once, then records one fixed-size sample per presented frame until stopped or full.", "examples": [ "local session_id = performance.start_logging(3600)" ], "history": [ "1.0.0: Package-controlled performance-log start added during Phase 15 closure." ], "id": "performance.start-logging", "manual_nodes": [ "phase.15", "engine-reference.extension-contract" ], "parameters": [ "maximum_samples: optional positive limit from 1 through 36000; defaults to 3600." ], "related": [ "performance", "performance.stop-logging", "developer.performance.current", "developer.performance.log" ], "returns": "A monotonically increasing process-local logging session identity.", "signature": "performance.start_logging(maximum_samples?) -> session_id", "usage": "Start one host-wide bounded logging session owned by the calling package. A new session replaces the prior completed log; an active log cannot be stolen or replaced." }, "errors": [], "fields": [], "id": "performance.start-logging", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "function", "name": "start_logging", "namespace": "performance", "owner": "app.ScriptPackageHost", "replacement": null, "side_effects": "replaces the prior completed log and begins bounded frame sampling", "signature": "performance.start_logging(maximum_samples?) -> session_id", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/performance.start-logging.html" }, { "authority": "host_lifecycle", "availability": "Phase 14 package callbacks", "deprecated": null, "description": "Stops the active performance log when the calling package owns it.", "determinism": "Host-created package identity and per-callback budgets.", "documentation": { "cost": "Constant-time logging-state transition with no simulation or rendering mutation.", "examples": [ "assert(performance.stop_logging())" ], "history": [ "1.0.0: Package-controlled performance-log stop added during Phase 15 closure." ], "id": "performance.stop-logging", "manual_nodes": [ "phase.15", "engine-reference.extension-contract" ], "parameters": [], "related": [ "performance", "performance.start-logging", "developer.performance.log", "developer.performance.log-samples" ], "returns": "True after the owned active log stops; invalid ownership or inactive logging raises a contained package error.", "signature": "performance.stop_logging() -> stopped", "usage": "Stop the active performance log from the package that started it. Samples and summary data remain available until the next logging session starts." }, "errors": [], "fields": [], "id": "performance.stop-logging", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "function", "name": "stop_logging", "namespace": "performance", "owner": "app.ScriptPackageHost", "replacement": null, "side_effects": "stops sampling while retaining detached log data", "signature": "performance.stop_logging() -> stopped", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/performance.stop-logging.html" }, { "authority": "restricted_request", "availability": "runtime API 1", "deprecated": null, "description": "Development-only Actor control requests routed through the normal owner.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Bounded by per-package command and queue limits; authoritative work occurs once through the fixed-tick owner.", "examples": [ "-- Access documented members through restricted.actor.crisis-override." ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "restricted.actor", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "restricted.actor.crisis-override" ], "returns": "A stable namespace table containing only the documented child symbols available to this package origin.", "signature": "namespace restricted.actor", "usage": "Use restricted.actor only to reach its registered child contracts. The namespace itself performs no query, mutation, lifecycle transition, or drawing." }, "errors": [], "fields": [], "id": "restricted.actor", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "namespace", "name": "Restricted Actor commands", "namespace": "restricted.actor", "owner": "game.control-authority", "replacement": null, "side_effects": "none", "signature": "namespace restricted.actor", "source_location": "src/app/script_api_catalog.cpp", "timing": "fixed_tick", "units": null, "url": "/api/v1/symbols/restricted.actor.html" }, { "authority": "restricted_request", "availability": "active-session", "deprecated": null, "description": "Requests development-only crisis control of one Actor through ControlAuthority.", "determinism": "record request and owner result in engine sequence order", "documentation": { "cost": "Bounded by per-package command and queue limits; authoritative work occurs once through the fixed-tick owner.", "examples": [ "local receipt = restricted.command.submit(\n \"restricted.actor.crisis-override\",\n {\n actor_id = ,\n expected_actor_revision = ,\n expected_authority_revision = \n },\n 1\n)" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "restricted.actor.crisis-override", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [ "actor_id: Actor identity whose control state will be changed.", "expected_actor_revision: Expected revision of the Actor state.", "expected_authority_revision: Expected revision of the Actor control-authority record." ], "related": [ "restricted.actor", "error.command-budget-exhausted", "error.command-owner-rejected", "error.command-queue-full", "error.invalid-command", "error.restricted-command" ], "returns": "A command receipt from the owning fixed-tick command service; acceptance does not mean the command has completed.", "signature": "restricted.actor.crisis-override(actor_id, expected_authority_revision, expected_actor_revision) -> command.receipt", "usage": "Submit restricted.actor.crisis-override through restricted.command.submit from a development package. Supply current expected revisions so the owning service can reject stale intent without partial mutation." }, "errors": [ "error.command-budget-exhausted", "error.command-owner-rejected", "error.command-queue-full", "error.invalid-command", "error.restricted-command" ], "fields": [ { "description": "Actor identity whose control state will be changed.", "id": "actor_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Expected revision of the Actor state.", "id": "expected_actor_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Expected revision of the Actor control-authority record.", "id": "expected_authority_revision", "required": true, "units": null, "value_type": "revision" } ], "id": "restricted.actor.crisis-override", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "command", "name": "Crisis override", "namespace": "restricted.actor", "owner": "game.control-authority", "replacement": null, "side_effects": "may interrupt autonomous control with a retained crisis override", "signature": "restricted.actor.crisis-override(actor_id, expected_authority_revision, expected_actor_revision) -> command.receipt", "source_location": "src/app/script_command_service.cpp", "timing": "fixed_tick", "units": null, "url": "/api/v1/symbols/restricted.actor.crisis-override.html" }, { "authority": "restricted_request", "availability": "runtime API 1", "deprecated": null, "description": "Development-only scenario capacity requests routed through the App owner.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Commands use the bounded fixed-tick queue.", "examples": [ "-- Submit children through restricted.command.submit." ], "history": [ "1.2.0: Restricted capacity-policy namespace added." ], "id": "restricted.capacity-policy", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [], "related": [ "restricted.capacity-policy.set-limit" ], "returns": "The restricted capacity-policy command contracts.", "signature": "namespace restricted.capacity-policy", "usage": "Request capacity changes only from development packages." }, "errors": [], "fields": [], "id": "restricted.capacity-policy", "introduced": { "display": "1.2.0", "major": 1, "minor": 2, "patch": 0 }, "kind": "namespace", "name": "Restricted capacity-policy commands", "namespace": "restricted.capacity-policy", "owner": "app.scenario-capacity-policy", "replacement": null, "side_effects": "none", "signature": "namespace restricted.capacity-policy", "source_location": "src/app/script_api_catalog.cpp", "timing": "fixed_tick", "units": null, "url": "/api/v1/symbols/restricted.capacity-policy.html" }, { "authority": "restricted_request", "availability": "active-session", "deprecated": null, "description": "Requests one revision-checked scenario capacity-limit change from a development package.", "determinism": "record request and owner result in engine sequence order; successful changes apply at the requested fixed tick", "documentation": { "cost": "One bounded command and owner validation.", "examples": [ "local receipt = restricted.command.submit(\"restricted.capacity-policy.set-limit\", {policy_id = \"population.maximum-live-actors\", value = 25000, expected_revision = current.revision}, 1)" ], "history": [ "1.2.0: Revision-checked capacity command added." ], "id": "restricted.capacity-policy.set-limit", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [ "policy_id: registered identity.", "value: unsigned limit.", "expected_revision: current revision." ], "related": [ "developer.capacity-policy.current", "events.capacity-policy.changed", "error.invalid-capacity-policy", "error.stale-capacity-policy", "error.capacity-limit-below-current-use" ], "returns": "A command receipt.", "signature": "restricted.capacity-policy.set-limit(policy_id, value, expected_revision) -> command.receipt", "usage": "Submit one registered limit with the current policy revision." }, "errors": [ "error.capacity-limit-below-current-use", "error.command-budget-exhausted", "error.command-owner-rejected", "error.command-queue-full", "error.invalid-capacity-policy", "error.invalid-command", "error.restricted-command", "error.stale-capacity-policy" ], "fields": [ { "description": "Expected scenario capacity-policy revision.", "id": "expected_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Registered scenario capacity-policy identity.", "id": "policy_id", "required": true, "units": null, "value_type": "string" }, { "description": "Requested capacity limit.", "id": "value", "required": true, "units": null, "value_type": "unsigned-integer" } ], "id": "restricted.capacity-policy.set-limit", "introduced": { "display": "1.2.0", "major": 1, "minor": 2, "patch": 0 }, "kind": "command", "name": "Set capacity-policy limit", "namespace": "restricted.capacity-policy", "owner": "app.scenario-capacity-policy", "replacement": null, "side_effects": "may change one scenario capacity limit without changing current owner state", "signature": "restricted.capacity-policy.set-limit(policy_id, value, expected_revision) -> command.receipt", "source_location": "src/app/script_command_service.cpp", "timing": "fixed_tick", "units": null, "url": "/api/v1/symbols/restricted.capacity-policy.set-limit.html" }, { "authority": "restricted_request", "availability": "runtime API 1", "deprecated": null, "description": "Development-only entry point for registered restricted commands.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Bounded by per-package command and queue limits; authoritative work occurs once through the fixed-tick owner.", "examples": [ "-- Access documented members through restricted.command.submit." ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "restricted.command", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "restricted.command.submit" ], "returns": "A stable namespace table containing only the documented child symbols available to this package origin.", "signature": "namespace restricted.command", "usage": "Use restricted.command only to reach its registered child contracts. The namespace itself performs no query, mutation, lifecycle transition, or drawing." }, "errors": [], "fields": [], "id": "restricted.command", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "namespace", "name": "Restricted command submission", "namespace": "restricted.command", "owner": "app.script-command-service", "replacement": null, "side_effects": "none", "signature": "namespace restricted.command", "source_location": "src/app/script_api_catalog.cpp", "timing": "fixed_tick", "units": null, "url": "/api/v1/symbols/restricted.command.html" }, { "authority": "restricted_request", "availability": "Phase 14 package callbacks", "deprecated": null, "description": "Submits one restricted command from a development package.", "determinism": "Host-created package identity and per-callback budgets.", "documentation": { "cost": "Bounded by per-package command and queue limits; authoritative work occurs once through the fixed-tick owner.", "examples": [ "local receipt = restricted.command.submit(\"restricted.actor.crisis-override\", arguments, 1)" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "restricted.command.submit", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [ "command_id: stable ID of a registered command.", "arguments: table matching the command descriptor fields.", "delay_ticks: optional bounded delay from the next fixed tick." ], "related": [ "restricted.command", "error.command-budget-exhausted", "error.restricted-command", "command.receipt" ], "returns": "A host-created receipt with request sequence, command ID, target tick, origin, and accepted status.", "signature": "restricted.command.submit(command_id, arguments, delay_ticks?) -> receipt", "usage": "Use only from development-origin packages. The host rejects this function for first-party standard packages before an owner command is queued." }, "errors": [ "error.command-budget-exhausted", "error.restricted-command" ], "fields": [], "id": "restricted.command.submit", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "function", "name": "submit", "namespace": "restricted.command", "owner": "app.ScriptPackageHost", "replacement": null, "side_effects": "submits a validated request to the existing command service", "signature": "restricted.command.submit(command_id, arguments, delay_ticks?) -> receipt", "source_location": "src/app/script_package_host.cpp", "timing": "fixed_tick", "units": null, "url": "/api/v1/symbols/restricted.command.submit.html" }, { "authority": "restricted_request", "availability": "runtime API 1", "deprecated": null, "description": "Development-only runtime tuning requests routed through the App owner.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Namespace lookup is constant-time; commands use the bounded fixed-tick queue.", "examples": [ "-- Submit registered children through restricted.command.submit." ], "history": [ "1.1.0: Restricted tuning namespace added." ], "id": "restricted.tuning", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [], "related": [ "restricted.command.submit", "restricted.tuning.set-value", "developer.tuning.values" ], "returns": "The documented restricted runtime tuning command contracts.", "signature": "namespace restricted.tuning", "usage": "Use restricted.tuning only from development packages to request engine-owned tuning changes." }, "errors": [], "fields": [], "id": "restricted.tuning", "introduced": { "display": "1.1.0", "major": 1, "minor": 1, "patch": 0 }, "kind": "namespace", "name": "Restricted tuning commands", "namespace": "restricted.tuning", "owner": "app.runtime-tuning", "replacement": null, "side_effects": "none", "signature": "namespace restricted.tuning", "source_location": "src/app/script_api_catalog.cpp", "timing": "fixed_tick", "units": null, "url": "/api/v1/symbols/restricted.tuning.html" }, { "authority": "restricted_request", "availability": "active-session", "deprecated": null, "description": "Requests one validated live tuning change from a development package.", "determinism": "record request and owner result in engine sequence order; effect begins next frame", "documentation": { "cost": "One bounded command submission and one constant-size owner validation at the target fixed tick.", "examples": [ "local receipt = restricted.command.submit(\"restricted.tuning.set-value\", {tuning_id = \"simulation.time-scale-basis-points\", value = 20000, expected_revision = current.revision}, 1)" ], "history": [ "1.1.0: Revision-checked runtime tuning command added." ], "id": "restricted.tuning.set-value", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [ "tuning_id: registered tuning identity.", "value: unsigned value in the registered units.", "expected_revision: current tuning-owner revision." ], "related": [ "developer.tuning.values", "events.tuning.changed", "error.invalid-tuning", "error.stale-tuning", "restricted.command.submit" ], "returns": "A command receipt. Wait for events.tuning.changed or the terminal receipt before treating the request as committed.", "signature": "restricted.tuning.set-value(tuning_id, value, expected_revision) -> command.receipt", "usage": "Submit one registered tuning value with the revision returned by developer.tuning.values. The owner validates the complete request and either commits one new revision or changes nothing." }, "errors": [ "error.command-budget-exhausted", "error.command-owner-rejected", "error.command-queue-full", "error.invalid-command", "error.invalid-tuning", "error.restricted-command", "error.stale-tuning" ], "fields": [ { "description": "Expected runtime tuning revision.", "id": "expected_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Registered runtime tuning identity.", "id": "tuning_id", "required": true, "units": null, "value_type": "string" }, { "description": "Requested value in the registered tuning unit.", "id": "value", "required": true, "units": null, "value_type": "unsigned-integer" } ], "id": "restricted.tuning.set-value", "introduced": { "display": "1.1.0", "major": 1, "minor": 1, "patch": 0 }, "kind": "command", "name": "Set tuning value", "namespace": "restricted.tuning", "owner": "app.runtime-tuning", "replacement": null, "side_effects": "may change future simulation wall-clock pace or presentation frame pacing", "signature": "restricted.tuning.set-value(tuning_id, value, expected_revision) -> command.receipt", "source_location": "src/app/script_command_service.cpp", "timing": "fixed_tick", "units": null, "url": "/api/v1/symbols/restricted.tuning.set-value.html" }, { "authority": "presentation", "availability": "runtime API 1", "deprecated": null, "description": "Backend-neutral semantic interface composition functions.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Namespace lookup is constant-time and performs no owner work.", "examples": [ "-- Access documented members through ui.begin-panel." ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "ui", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.begin-panel", "ui.button", "ui.end-panel", "ui.menu", "ui.progress", "ui.row", "ui.select-provider", "ui.set-theme" ], "returns": "A stable namespace table containing only the documented child symbols available to this package origin.", "signature": "namespace ui", "usage": "Use ui only to reach its registered child contracts. The namespace itself performs no query, mutation, lifecycle transition, or drawing." }, "errors": [], "fields": [], "id": "ui", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "namespace", "name": "Interface", "namespace": "ui", "owner": "app.ScriptPackageHost", "replacement": null, "side_effects": "none", "signature": "namespace ui", "source_location": "src/app/script_api_catalog.cpp", "timing": "composition", "units": null, "url": "/api/v1/symbols/ui.html" }, { "authority": "presentation", "availability": "runtime API 1", "deprecated": null, "description": "Stable logical action identities independent of physical input.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Namespace lookup is constant-time and performs no owner work.", "examples": [ "-- Access documented members through ui.action.resource-counts.toggle." ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "ui.action", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.action.resource-counts.toggle" ], "returns": "A stable namespace table containing only the documented child symbols available to this package origin.", "signature": "namespace ui.action", "usage": "Use ui.action only to reach its registered child contracts. The namespace itself performs no query, mutation, lifecycle transition, or drawing." }, "errors": [], "fields": [], "id": "ui.action", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "namespace", "name": "Interface actions", "namespace": "ui.action", "owner": "controls.ControlState", "replacement": null, "side_effects": "none", "signature": "namespace ui.action", "source_location": "src/app/script_api_catalog.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.html" }, { "authority": "presentation", "availability": "runtime API 1", "deprecated": null, "description": "Logical actions used by the standard Actor interface.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Namespace lookup is constant-time and performs no owner work.", "examples": [ "-- Access documented members through ui.action.actor.release-control." ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "ui.action.actor", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.action.actor.release-control", "ui.action.actor.take-control" ], "returns": "A stable namespace table containing only the documented child symbols available to this package origin.", "signature": "namespace ui.action.actor", "usage": "Use ui.action.actor only to reach its registered child contracts. The namespace itself performs no query, mutation, lifecycle transition, or drawing." }, "errors": [], "fields": [], "id": "ui.action.actor", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "namespace", "name": "Actor interface actions", "namespace": "ui.action.actor", "owner": "controls.ControlState", "replacement": null, "side_effects": "none", "signature": "namespace ui.action.actor", "source_location": "src/app/script_api_catalog.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.actor.html" }, { "authority": "presentation", "availability": "Phase 14H standard interface", "deprecated": null, "description": "Contributes one currency unit from the selected actor to their household.", "determinism": "Action identity is stable and independent of physical input.", "documentation": { "cost": "One package action callback, three detached queries, and one bounded command submission.", "examples": [ "ui.button(\"Contribute One\", \"ui.action.actor.contribute-one\", \"Move one coin to this villager's household\", 1)" ], "history": [ "1.4.0: Standard one-unit Household contribution action added for Phase 16D2." ], "id": "ui.action.actor.contribute-one", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [], "related": [ "command.money.contribute", "lifecycle.handle-action", "world.actor.wealth", "world.household.wealth" ], "returns": "No direct value. The package handler submits command.money.contribute for one minor currency unit.", "signature": "ui.action.actor.contribute-one", "usage": "Bind this action to a standard-interface control after the selected Actor is directly controlled and both custody queries are available." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.actor.contribute-one", "introduced": { "display": "1.4.0", "major": 1, "minor": 4, "patch": 0 }, "kind": "action", "name": "actor.contribute-one", "namespace": "ui.action.actor", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the package action callback; gameplay requests still use commands.", "signature": "ui.action.actor.contribute-one", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.actor.contribute-one.html" }, { "authority": "presentation", "availability": "Phase 14H standard interface", "deprecated": null, "description": "Returns the selected actor to autonomous control.", "determinism": "Action identity is stable and independent of physical input.", "documentation": { "cost": "Constant-size contract lookup or bounded retained-record access.", "examples": [ "ui.button(\"Action\", \"ui.action.actor.release-control\", \"Describe the action\", 1)" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "ui.action.actor.release-control", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.action.actor", "error.invalid-action", "lifecycle.handle-action" ], "returns": "No direct value. The host dispatches the stable action ID to the package action handler.", "signature": "ui.action.actor.release-control", "usage": "Bind a semantic UI control to ui.action.actor.release-control. The host validates the action and dispatches it to lifecycle.handle-action; the action does not mutate gameplay by itself." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.actor.release-control", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "action", "name": "actor.release-control", "namespace": "ui.action.actor", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the package action callback; gameplay requests still use commands.", "signature": "ui.action.actor.release-control", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.actor.release-control.html" }, { "authority": "presentation", "availability": "Phase 14H standard interface", "deprecated": null, "description": "Requests direct control of the selected actor.", "determinism": "Action identity is stable and independent of physical input.", "documentation": { "cost": "Constant-size contract lookup or bounded retained-record access.", "examples": [ "ui.button(\"Action\", \"ui.action.actor.take-control\", \"Describe the action\", 1)" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "ui.action.actor.take-control", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.action.actor", "error.invalid-action", "lifecycle.handle-action" ], "returns": "No direct value. The host dispatches the stable action ID to the package action handler.", "signature": "ui.action.actor.take-control", "usage": "Bind a semantic UI control to ui.action.actor.take-control. The host validates the action and dispatches it to lifecycle.handle-action; the action does not mutate gameplay by itself." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.actor.take-control", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "action", "name": "actor.take-control", "namespace": "ui.action.actor", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the package action callback; gameplay requests still use commands.", "signature": "ui.action.actor.take-control", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.actor.take-control.html" }, { "authority": "presentation", "availability": "runtime API 1", "deprecated": null, "description": "Logical actions used by the development replacement proof.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Namespace lookup is constant-time and performs no owner work.", "examples": [ "-- Access documented members through ui.action.composition-proof.crisis-override." ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "ui.action.composition-proof", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.action.composition-proof.crisis-override", "ui.action.composition-proof.take-control", "ui.action.composition-proof.use-alternate", "ui.action.composition-proof.use-standard" ], "returns": "A stable namespace table containing only the documented child symbols available to this package origin.", "signature": "namespace ui.action.composition-proof", "usage": "Use ui.action.composition-proof only to reach its registered child contracts. The namespace itself performs no query, mutation, lifecycle transition, or drawing." }, "errors": [], "fields": [], "id": "ui.action.composition-proof", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "namespace", "name": "Composition proof actions", "namespace": "ui.action.composition-proof", "owner": "controls.ControlState", "replacement": null, "side_effects": "none", "signature": "namespace ui.action.composition-proof", "source_location": "src/app/script_api_catalog.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.composition-proof.html" }, { "authority": "presentation", "availability": "Phase 14I replacement and extension proof", "deprecated": null, "description": "Requests the development-restricted crisis control transition.", "determinism": "Action identity is independent of physical input.", "documentation": { "cost": "Constant-size contract lookup or bounded retained-record access.", "examples": [ "ui.button(\"Action\", \"ui.action.composition-proof.crisis-override\", \"Describe the action\", 1)" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "ui.action.composition-proof.crisis-override", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.action.composition-proof", "error.invalid-action", "lifecycle.handle-action" ], "returns": "No direct value. The host dispatches the stable action ID to the package action handler.", "signature": "ui.action.composition-proof.crisis-override", "usage": "Bind a semantic UI control to ui.action.composition-proof.crisis-override. The host validates the action and dispatches it to lifecycle.handle-action; the action does not mutate gameplay by itself." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.composition-proof.crisis-override", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "action", "name": "composition-proof.crisis-override", "namespace": "ui.action.composition-proof", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the owning package action callback through stable package identity.", "signature": "ui.action.composition-proof.crisis-override", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.composition-proof.crisis-override.html" }, { "authority": "presentation", "availability": "Phase 14I replacement and extension proof", "deprecated": null, "description": "Requests normal direct control from the composition proof surface.", "determinism": "Action identity is independent of physical input.", "documentation": { "cost": "Constant-size contract lookup or bounded retained-record access.", "examples": [ "ui.button(\"Action\", \"ui.action.composition-proof.take-control\", \"Describe the action\", 1)" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "ui.action.composition-proof.take-control", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.action.composition-proof", "error.invalid-action", "lifecycle.handle-action" ], "returns": "No direct value. The host dispatches the stable action ID to the package action handler.", "signature": "ui.action.composition-proof.take-control", "usage": "Bind a semantic UI control to ui.action.composition-proof.take-control. The host validates the action and dispatches it to lifecycle.handle-action; the action does not mutate gameplay by itself." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.composition-proof.take-control", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "action", "name": "composition-proof.take-control", "namespace": "ui.action.composition-proof", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the owning package action callback through stable package identity.", "signature": "ui.action.composition-proof.take-control", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.composition-proof.take-control.html" }, { "authority": "presentation", "availability": "Phase 14I replacement and extension proof", "deprecated": null, "description": "Selects the alternate composition proof player HUD provider.", "determinism": "Action identity is independent of physical input.", "documentation": { "cost": "Constant-size contract lookup or bounded retained-record access.", "examples": [ "ui.button(\"Action\", \"ui.action.composition-proof.use-alternate\", \"Describe the action\", 1)" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "ui.action.composition-proof.use-alternate", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.action.composition-proof", "error.invalid-action", "lifecycle.handle-action" ], "returns": "No direct value. The host dispatches the stable action ID to the package action handler.", "signature": "ui.action.composition-proof.use-alternate", "usage": "Bind a semantic UI control to ui.action.composition-proof.use-alternate. The host validates the action and dispatches it to lifecycle.handle-action; the action does not mutate gameplay by itself." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.composition-proof.use-alternate", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "action", "name": "composition-proof.use-alternate", "namespace": "ui.action.composition-proof", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the owning package action callback through stable package identity.", "signature": "ui.action.composition-proof.use-alternate", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.composition-proof.use-alternate.html" }, { "authority": "presentation", "availability": "Phase 14I replacement and extension proof", "deprecated": null, "description": "Restores the standard player HUD provider.", "determinism": "Action identity is independent of physical input.", "documentation": { "cost": "Constant-size contract lookup or bounded retained-record access.", "examples": [ "ui.button(\"Action\", \"ui.action.composition-proof.use-standard\", \"Describe the action\", 1)" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "ui.action.composition-proof.use-standard", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.action.composition-proof", "error.invalid-action", "lifecycle.handle-action" ], "returns": "No direct value. The host dispatches the stable action ID to the package action handler.", "signature": "ui.action.composition-proof.use-standard", "usage": "Bind a semantic UI control to ui.action.composition-proof.use-standard. The host validates the action and dispatches it to lifecycle.handle-action; the action does not mutate gameplay by itself." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.composition-proof.use-standard", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "action", "name": "composition-proof.use-standard", "namespace": "ui.action.composition-proof", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the owning package action callback through stable package identity.", "signature": "ui.action.composition-proof.use-standard", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.composition-proof.use-standard.html" }, { "authority": "presentation", "availability": "runtime API 1", "deprecated": null, "description": "Logical actions used by the standard regional strategy view.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Namespace lookup is constant-time.", "examples": [ "-- Open the regional view through ui.action.empire.open." ], "history": [ "1.19.0: Empire-view action namespace added for Phase 19Q9F." ], "id": "ui.action.empire", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.layout.canvas", "world.region.known", "world.route.known" ], "returns": "The registered Empire-view action contracts.", "signature": "namespace ui.action.empire", "usage": "Use this namespace for transient Empire-view navigation and selection actions. Its children only change package presentation state or request camera movement." }, "errors": [], "fields": [], "id": "ui.action.empire", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "namespace", "name": "Empire interface actions", "namespace": "ui.action.empire", "owner": "controls.ControlState", "replacement": null, "side_effects": "none", "signature": "namespace ui.action.empire", "source_location": "src/app/script_api_catalog.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.empire.html" }, { "authority": "presentation", "availability": "Phase 19Q9F regional and event interface", "deprecated": null, "description": "Closes the standard regional strategy view.", "determinism": "Action identity is stable and independent of physical input.", "documentation": { "cost": "One bounded package action callback.", "examples": [ "ui.button(\"Close\", \"ui.action.empire.close\", \"Close empire view\", 1)" ], "history": [ "1.19.0: Empire-view close action added for Phase 19Q9F." ], "id": "ui.action.empire.close", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.action.empire.open", "ui.layout.canvas" ], "returns": "No gameplay value.", "signature": "ui.action.empire.close", "usage": "Close the standard regional map and its inspectors without changing simulation state." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.empire.close", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "action", "name": "empire.close", "namespace": "ui.action.empire", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the package action callback; gameplay requests still use commands.", "signature": "ui.action.empire.close", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.empire.close.html" }, { "authority": "presentation", "availability": "Phase 19Q9F regional and event interface", "deprecated": null, "description": "Selects one stable World-grid position on the regional map.", "determinism": "Action identity is stable and independent of physical input.", "documentation": { "cost": "One bounded action callback and one detached camera intent.", "examples": [ "ui.surface(\"region_map\", 1.6, \"ui.action.empire.map-select\")" ], "history": [ "1.19.0: Regional-map camera selection added for Phase 19Q9F." ], "id": "ui.action.empire.map-select", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.pan-camera", "ui.layout.canvas", "ui.spatial-surface" ], "returns": "No gameplay value.", "signature": "ui.action.empire.map-select", "usage": "Receive a regional-map World cell as row_id and retain a camera-centering target for the next composition." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.empire.map-select", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "action", "name": "empire.map-select", "namespace": "ui.action.empire", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the package action callback; gameplay requests still use commands.", "signature": "ui.action.empire.map-select", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.empire.map-select.html" }, { "authority": "presentation", "availability": "Phase 19Q9F regional and event interface", "deprecated": null, "description": "Opens the standard regional strategy view.", "determinism": "Action identity is stable and independent of physical input.", "documentation": { "cost": "One bounded package action callback.", "examples": [ "ui.button(\"Empire\", \"ui.action.empire.open\", \"Open empire view (M)\", 1)" ], "history": [ "1.19.0: Empire-view open action added for Phase 19Q9F." ], "id": "ui.action.empire.open", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.action.empire.close", "ui.layout.canvas" ], "returns": "No gameplay value.", "signature": "ui.action.empire.open", "usage": "Open the standard full-viewport regional map and close other modal player views without changing simulation state." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.empire.open", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "action", "name": "empire.open", "namespace": "ui.action.empire", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the package action callback; gameplay requests still use commands.", "signature": "ui.action.empire.open", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.empire.open.html" }, { "authority": "presentation", "availability": "Phase 19Q9F regional and event interface", "deprecated": null, "description": "Selects one stable expedition row.", "determinism": "Action identity is stable and independent of physical input.", "documentation": { "cost": "One bounded package action callback.", "examples": [ "ui.list(\"ui.action.empire.select-expedition\", expedition_rows, {visible_rows = 4})" ], "history": [ "1.19.0: Empire expedition selection added for Phase 19Q9F." ], "id": "ui.action.empire.select-expedition", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [], "related": [ "world.expedition.records", "ui.list" ], "returns": "No gameplay value.", "signature": "ui.action.empire.select-expedition", "usage": "Select an expedition record by stable row_id for the regional expedition strip. The action does not issue expedition commands." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.empire.select-expedition", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "action", "name": "empire.select-expedition", "namespace": "ui.action.empire", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the package action callback; gameplay requests still use commands.", "signature": "ui.action.empire.select-expedition", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.empire.select-expedition.html" }, { "authority": "presentation", "availability": "Phase 19Q9F regional and event interface", "deprecated": null, "description": "Selects one stable Faction standing row.", "determinism": "Action identity is stable and independent of physical input.", "documentation": { "cost": "One bounded package action callback.", "examples": [ "ui.list(\"ui.action.empire.select-faction\", faction_rows, {visible_rows = 5})" ], "history": [ "1.19.0: Empire Faction selection added for Phase 19Q9F." ], "id": "ui.action.empire.select-faction", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [], "related": [ "world.faction.standings", "ui.list" ], "returns": "No gameplay value.", "signature": "ui.action.empire.select-faction", "usage": "Select a Faction standing by stable row_id for regional presentation. The action does not change diplomatic state." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.empire.select-faction", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "action", "name": "empire.select-faction", "namespace": "ui.action.empire", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the package action callback; gameplay requests still use commands.", "signature": "ui.action.empire.select-faction", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.empire.select-faction.html" }, { "authority": "presentation", "availability": "Phase 19Q9F regional and event interface", "deprecated": null, "description": "Selects one transient regional map lens.", "determinism": "Action identity is stable and independent of physical input.", "documentation": { "cost": "One bounded package action callback.", "examples": [ "ui.list(\"ui.action.empire.select-lens\", lens_rows, {visible_rows = 6})" ], "history": [ "1.19.0: Empire lens selection added for Phase 19Q9F." ], "id": "ui.action.empire.select-lens", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.action.empire", "ui.list" ], "returns": "No gameplay value.", "signature": "ui.action.empire.select-lens", "usage": "Select one registered regional lens by row_id. The standard package retains only the active lens name." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.empire.select-lens", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "action", "name": "empire.select-lens", "namespace": "ui.action.empire", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the package action callback; gameplay requests still use commands.", "signature": "ui.action.empire.select-lens", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.empire.select-lens.html" }, { "authority": "presentation", "availability": "Phase 19Q9F regional and event interface", "deprecated": null, "description": "Selects one stable known route for regional inspection.", "determinism": "Action identity is stable and independent of physical input.", "documentation": { "cost": "One bounded package action callback.", "examples": [ "ui.list(\"ui.action.empire.select-route\", route_rows, {visible_rows = 6})" ], "history": [ "1.19.0: Empire route selection added for Phase 19Q9F." ], "id": "ui.action.empire.select-route", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [], "related": [ "world.route.known", "ui.list" ], "returns": "No gameplay value.", "signature": "ui.action.empire.select-route", "usage": "Select a route row by stable row_id so the regional inspector can explain its retained knowledge, pressure, and danger." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.empire.select-route", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "action", "name": "empire.select-route", "namespace": "ui.action.empire", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the package action callback; gameplay requests still use commands.", "signature": "ui.action.empire.select-route", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.empire.select-route.html" }, { "authority": "presentation", "availability": "runtime API 1", "deprecated": null, "description": "Logical actions used by the standard causal history feed.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Namespace lookup is constant-time.", "examples": [ "-- Open the event feed through ui.action.events.open." ], "history": [ "1.19.0: Event-feed action namespace added for Phase 19Q9F." ], "id": "ui.action.events", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [], "related": [ "world.settlement.life-events", "world.settlement.social-chronicle" ], "returns": "The registered event-feed action contracts.", "signature": "namespace ui.action.events", "usage": "Use this namespace for the standard event-feed view, tabs, and retained entry selection. The namespace has no gameplay authority." }, "errors": [], "fields": [], "id": "ui.action.events", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "namespace", "name": "Event-feed actions", "namespace": "ui.action.events", "owner": "controls.ControlState", "replacement": null, "side_effects": "none", "signature": "namespace ui.action.events", "source_location": "src/app/script_api_catalog.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.events.html" }, { "authority": "presentation", "availability": "Phase 19Q9F regional and event interface", "deprecated": null, "description": "Closes the standard causal event feed.", "determinism": "Action identity is stable and independent of physical input.", "documentation": { "cost": "One bounded package action callback.", "examples": [ "ui.button(\"Close\", \"ui.action.events.close\", \"Close event feed\", 1)" ], "history": [ "1.19.0: Event-feed close action added for Phase 19Q9F." ], "id": "ui.action.events.close", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.action.events.open", "ui.action.events.select-entry" ], "returns": "No gameplay value.", "signature": "ui.action.events.close", "usage": "Close the standard event feed without changing simulation state or retained gameplay events." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.events.close", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "action", "name": "events.close", "namespace": "ui.action.events", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the package action callback; gameplay requests still use commands.", "signature": "ui.action.events.close", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.events.close.html" }, { "authority": "presentation", "availability": "Phase 19Q9F regional and event interface", "deprecated": null, "description": "Opens the standard causal event feed.", "determinism": "Action identity is stable and independent of physical input.", "documentation": { "cost": "One bounded package action callback.", "examples": [ "ui.button(\"Events\", \"ui.action.events.open\", \"Open event feed (V)\", 1)" ], "history": [ "1.19.0: Event-feed open action added for Phase 19Q9F." ], "id": "ui.action.events.open", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.action.events.close", "ui.action.events.select-tab" ], "returns": "No gameplay value.", "signature": "ui.action.events.open", "usage": "Open the standard grouped event feed and close other modal player views without changing simulation state." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.events.open", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "action", "name": "events.open", "namespace": "ui.action.events", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the package action callback; gameplay requests still use commands.", "signature": "ui.action.events.open", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.events.open.html" }, { "authority": "presentation", "availability": "Phase 19Q9F regional and event interface", "deprecated": null, "description": "Selects one stable event row and requests its map location.", "determinism": "Action identity is stable and independent of physical input.", "documentation": { "cost": "One bounded package action callback and at most one detached camera intent.", "examples": [ "ui.list(\"ui.action.events.select-entry\", event_rows, {visible_rows = 8})" ], "history": [ "1.19.0: Event-feed entry selection added for Phase 19Q9F." ], "id": "ui.action.events.select-entry", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.pan-camera", "world.settlement.social-chronicle", "world.construction.active" ], "returns": "No gameplay value.", "signature": "ui.action.events.select-entry", "usage": "Select one retained event row by stable row_id, show its explanation, and center the camera when the event carries a known site." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.events.select-entry", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "action", "name": "events.select-entry", "namespace": "ui.action.events", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the package action callback; gameplay requests still use commands.", "signature": "ui.action.events.select-entry", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.events.select-entry.html" }, { "authority": "presentation", "availability": "Phase 19Q9F regional and event interface", "deprecated": null, "description": "Selects one stable event-feed category.", "determinism": "Action identity is stable and independent of physical input.", "documentation": { "cost": "One bounded package action callback.", "examples": [ "ui.tabs(\"ui.action.events.select-tab\", event_tabs, active_tab)" ], "history": [ "1.19.0: Event-feed tab selection added for Phase 19Q9F." ], "id": "ui.action.events.select-tab", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.tabs", "ui.action.events.select-entry" ], "returns": "No gameplay value. The package retains only the active tab index.", "signature": "ui.action.events.select-tab", "usage": "Select the All, Village, People, Work, or Threats event-feed tab using the activation row_id." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.events.select-tab", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "action", "name": "events.select-tab", "namespace": "ui.action.events", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the package action callback; gameplay requests still use commands.", "signature": "ui.action.events.select-tab", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.events.select-tab.html" }, { "authority": "host_lifecycle", "availability": "runtime API 1", "deprecated": null, "description": "Logical host actions that operate on the package graph.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Runs at a frame boundary and is bounded by package count and reload validation work.", "examples": [ "-- Access documented members through ui.action.packages.reload." ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "ui.action.packages", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.action.packages.reload" ], "returns": "A stable namespace table containing only the documented child symbols available to this package origin.", "signature": "namespace ui.action.packages", "usage": "Use ui.action.packages only to reach its registered child contracts. The namespace itself performs no query, mutation, lifecycle transition, or drawing." }, "errors": [], "fields": [], "id": "ui.action.packages", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "namespace", "name": "Package actions", "namespace": "ui.action.packages", "owner": "controls.ControlState", "replacement": null, "side_effects": "none", "signature": "namespace ui.action.packages", "source_location": "src/app/script_api_catalog.cpp", "timing": "frame_boundary", "units": null, "url": "/api/v1/symbols/ui.action.packages.html" }, { "authority": "host_lifecycle", "availability": "Phase 14J transactional reload", "deprecated": null, "description": "Reloads the complete script package graph at a safe frame boundary.", "determinism": "The action has a stable identity and a configurable physical binding.", "documentation": { "cost": "Runs at a frame boundary and is bounded by package count and reload validation work.", "examples": [ "ui.button(\"Action\", \"ui.action.packages.reload\", \"Describe the action\", 1)" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "ui.action.packages.reload", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.action.packages", "error.package-reload", "lifecycle.handle-action" ], "returns": "No direct value. The host dispatches the stable action ID to the package action handler.", "signature": "ui.action.packages.reload", "usage": "Bind a semantic UI control to ui.action.packages.reload. The host validates the action and dispatches it to lifecycle.handle-action; the action does not mutate gameplay by itself." }, "errors": [ "error.package-reload" ], "fields": [], "id": "ui.action.packages.reload", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "action", "name": "reload", "namespace": "ui.action.packages", "owner": "controls.ControlState", "replacement": null, "side_effects": "Atomically replaces the package graph after validation and proof composition.", "signature": "ui.action.packages.reload", "source_location": "src/app/script_package_host.cpp", "timing": "frame_boundary", "units": null, "url": "/api/v1/symbols/ui.action.packages.reload.html" }, { "authority": "presentation", "availability": "Phase 14G interface action registry", "deprecated": null, "description": "Logical Controls-owned action for resource panel visibility.", "determinism": "Action identity is stable and independent of physical input.", "documentation": { "cost": "Constant-size contract lookup or bounded retained-record access.", "examples": [ "ui.button(\"Action\", \"ui.action.resource-counts.toggle\", \"Describe the action\", 1)" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "ui.action.resource-counts.toggle", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.action", "error.action-collision", "lifecycle.handle-action" ], "returns": "No direct value. The host dispatches the stable action ID to the package action handler.", "signature": "ui.action.resource-counts.toggle", "usage": "Bind a semantic UI control to ui.action.resource-counts.toggle. The host validates the action and dispatches it to lifecycle.handle-action; the action does not mutate gameplay by itself." }, "errors": [ "error.action-collision" ], "fields": [], "id": "ui.action.resource-counts.toggle", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "action", "name": "resource-counts.toggle", "namespace": "ui.action", "owner": "controls.ControlState", "replacement": null, "side_effects": "Changes host-owned interface visibility only.", "signature": "ui.action.resource-counts.toggle", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.resource-counts.toggle.html" }, { "authority": "presentation", "availability": "runtime API 1", "deprecated": null, "description": "Logical actions used by the standard selection interface.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Namespace lookup is constant-time and performs no simulation owner visit.", "examples": [ "ui.list(\"ui.action.selection.focus\", actor_rows, {visible_rows = 6})" ], "history": [ "1.19.0: Selection action namespace added for Phase 19Q9C." ], "id": "ui.action.selection", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.action.selection.focus", "ui.list", "world.selection.current" ], "returns": "The bounded selection actions registered for the standard player interface.", "signature": "namespace ui.action.selection", "usage": "Use stable selection actions to change only the package-owned focused row within the current detached world selection. Gameplay state remains unchanged." }, "errors": [], "fields": [], "id": "ui.action.selection", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "namespace", "name": "Selection interface actions", "namespace": "ui.action.selection", "owner": "controls.ControlState", "replacement": null, "side_effects": "none", "signature": "namespace ui.action.selection", "source_location": "src/app/script_api_catalog.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.selection.html" }, { "authority": "presentation", "availability": "Phase 19Q9C selection panel", "deprecated": null, "description": "Focuses one stable Actor row in the current multiple selection.", "determinism": "Action identity is stable and independent of physical input.", "documentation": { "cost": "One bounded action callback and no simulation mutation.", "examples": [ "function handle_action(action_id, row_id)\n if action_id == \"ui.action.selection.focus\" then\n selected_actor_row_id = row_id\n end\nend" ], "history": [ "1.19.0: Stable multiple-selection focus added for Phase 19Q9C." ], "id": "ui.action.selection.focus", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.action.selection", "ui.list", "lifecycle.handle-action", "world.actor.info" ], "returns": "No gameplay value. The owning package retains only the selected row identity.", "signature": "ui.action.selection.focus", "usage": "Focus one stable Actor row from the current multiple selection so the standard panel can show that Actor's detached details and contextual controls." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.selection.focus", "introduced": { "display": "1.9.0", "major": 1, "minor": 9, "patch": 0 }, "kind": "action", "name": "selection.focus", "namespace": "ui.action.selection", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the package action callback; gameplay requests still use commands.", "signature": "ui.action.selection.focus", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.selection.focus.html" }, { "authority": "presentation", "availability": "runtime API 1", "deprecated": null, "description": "Logical actions used by standard settlement direction.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Constant-time action lookup.", "examples": [ "-- Bind controls to ui.action.settlement.designate or a placement action." ], "history": [ "1.5.0: Standard settlement direction actions added for Phase 16D.", "1.9.0: No-selection village project priority actions added." ], "id": "ui.action.settlement", "manual_nodes": [ "phase.16", "phase.19", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.action.settlement.designate", "ui.action.settlement.cancel-construction", "ui.action.settlement.focus-priority-high", "ui.action.settlement.focus-priority-normal", "lifecycle.handle-action" ], "returns": "The registered settlement action IDs.", "signature": "namespace ui.action.settlement", "usage": "Use these first-party standard-interface actions to browse authored projects, move the placement cursor, designate or cancel construction, and change the current village project's real Work priority." }, "errors": [], "fields": [], "id": "ui.action.settlement", "introduced": { "display": "1.5.0", "major": 1, "minor": 5, "patch": 0 }, "kind": "namespace", "name": "Settlement interface actions", "namespace": "ui.action.settlement", "owner": "controls.ControlState", "replacement": null, "side_effects": "none", "signature": "namespace ui.action.settlement", "source_location": "src/app/script_api_catalog.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.settlement.html" }, { "authority": "presentation", "availability": "Phase 16D player direction", "deprecated": null, "description": "Requests cancellation of the displayed active construction project.", "determinism": "Action identity is stable and independent of physical input.", "documentation": { "cost": "One action callback, one bounded query, and one command submission.", "examples": [ "ui.button(\"Cancel Project\", \"ui.action.settlement.cancel-construction\", \"Cancel the active project\", 1)" ], "history": [ "1.5.0: Standard construction cancellation action added." ], "id": "ui.action.settlement.cancel-construction", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.action.settlement", "command.construction.cancel" ], "returns": "No direct value; the package handler submits command.construction.cancel.", "signature": "ui.action.settlement.cancel-construction", "usage": "Cancel the active construction row currently displayed by the standard settlement panel." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.settlement.cancel-construction", "introduced": { "display": "1.5.0", "major": 1, "minor": 5, "patch": 0 }, "kind": "action", "name": "settlement.cancel-construction", "namespace": "ui.action.settlement", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the package action callback; gameplay requests still use commands.", "signature": "ui.action.settlement.cancel-construction", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.settlement.cancel-construction.html" }, { "authority": "presentation", "availability": "Phase 19Q9D settlement sheet", "deprecated": null, "description": "Closes the settlement overview sheet.", "determinism": "Action identity is stable and independent of physical input.", "documentation": { "cost": "One bounded package action callback.", "examples": [ "ui.button(\"Close\", \"ui.action.settlement.close-sheet\", \"Close settlement overview\", 1)" ], "history": [ "1.19.0: Settlement sheet close action added for Phase 19Q9D." ], "id": "ui.action.settlement.close-sheet", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.action.settlement.open-sheet", "ui.layout.sheet" ], "returns": "No gameplay value.", "signature": "ui.action.settlement.close-sheet", "usage": "Close the standard settlement overview without mutating simulation state." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.settlement.close-sheet", "introduced": { "display": "1.9.0", "major": 1, "minor": 9, "patch": 0 }, "kind": "action", "name": "settlement.close-sheet", "namespace": "ui.action.settlement", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the package action callback; gameplay requests still use commands.", "signature": "ui.action.settlement.close-sheet", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.settlement.close-sheet.html" }, { "authority": "presentation", "availability": "Phase 16D player direction", "deprecated": null, "description": "Requests designation of the displayed settlement project.", "determinism": "Action identity is stable and independent of physical input.", "documentation": { "cost": "One action callback, bounded detached reads, and one command submission.", "examples": [ "ui.button(\"Designate\", \"ui.action.settlement.designate\", \"Designate this building\", 1)" ], "history": [ "1.5.0: Standard building designation action added." ], "id": "ui.action.settlement.designate", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.action.settlement", "command.construction.designate" ], "returns": "No direct value; the package handler submits command.construction.designate.", "signature": "ui.action.settlement.designate", "usage": "Designate the displayed authored project at the current standard-interface placement cursor." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.settlement.designate", "introduced": { "display": "1.5.0", "major": 1, "minor": 5, "patch": 0 }, "kind": "action", "name": "settlement.designate", "namespace": "ui.action.settlement", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the package action callback; gameplay requests still use commands.", "signature": "ui.action.settlement.designate", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.settlement.designate.html" }, { "authority": "presentation", "availability": "Phase 16D player direction", "deprecated": null, "description": "Raises the current village project's player priority.", "determinism": "Action identity is stable and independent of physical input.", "documentation": { "cost": "One action callback and one command submission.", "examples": [ "ui.button(\"Prioritize Project\", \"ui.action.settlement.focus-priority-high\", \"Prioritize the current project\", 1)" ], "history": [ "1.9.0: No-selection village project priority action added." ], "id": "ui.action.settlement.focus-priority-high", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.action.settlement", "world.construction.active", "command.work.set-priority" ], "returns": "No direct value; the package handler submits command.work.set-priority with the detached Job revision.", "signature": "ui.action.settlement.focus-priority-high", "usage": "Raise the active village construction project's real Work job to maximum player priority from the normal no-selection interface." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.settlement.focus-priority-high", "introduced": { "display": "1.9.0", "major": 1, "minor": 9, "patch": 0 }, "kind": "action", "name": "settlement.focus-priority-high", "namespace": "ui.action.settlement", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the package action callback; gameplay requests still use commands.", "signature": "ui.action.settlement.focus-priority-high", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.settlement.focus-priority-high.html" }, { "authority": "presentation", "availability": "Phase 16D player direction", "deprecated": null, "description": "Returns the current village project to normal player priority.", "determinism": "Action identity is stable and independent of physical input.", "documentation": { "cost": "One action callback and one command submission.", "examples": [ "ui.button(\"Clear Project Priority\", \"ui.action.settlement.focus-priority-normal\", \"Restore normal project priority\", 1)" ], "history": [ "1.9.0: No-selection village project priority action added." ], "id": "ui.action.settlement.focus-priority-normal", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.action.settlement", "world.construction.active", "command.work.set-priority" ], "returns": "No direct value; the package handler submits command.work.set-priority with the detached Job revision.", "signature": "ui.action.settlement.focus-priority-normal", "usage": "Clear the player priority contribution from the active village construction project's real Work job." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.settlement.focus-priority-normal", "introduced": { "display": "1.9.0", "major": 1, "minor": 9, "patch": 0 }, "kind": "action", "name": "settlement.focus-priority-normal", "namespace": "ui.action.settlement", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the package action callback; gameplay requests still use commands.", "signature": "ui.action.settlement.focus-priority-normal", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.settlement.focus-priority-normal.html" }, { "authority": "presentation", "availability": "Phase 19Q9D settlement sheet", "deprecated": null, "description": "Opens the settlement overview sheet.", "determinism": "Action identity is stable and independent of physical input.", "documentation": { "cost": "One bounded package action callback.", "examples": [ "ui.button(\"Settlement\", \"ui.action.settlement.open-sheet\", \"Open settlement overview\", 1)" ], "history": [ "1.19.0: Settlement sheet open action added for Phase 19Q9D." ], "id": "ui.action.settlement.open-sheet", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.action.settlement.close-sheet", "ui.layout.sheet" ], "returns": "No gameplay value.", "signature": "ui.action.settlement.open-sheet", "usage": "Open the standard settlement overview using package-owned transient view state." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.settlement.open-sheet", "introduced": { "display": "1.9.0", "major": 1, "minor": 9, "patch": 0 }, "kind": "action", "name": "settlement.open-sheet", "namespace": "ui.action.settlement", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the package action callback; gameplay requests still use commands.", "signature": "ui.action.settlement.open-sheet", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.settlement.open-sheet.html" }, { "authority": "presentation", "availability": "Phase 19Q9E spatial interface", "deprecated": null, "description": "Begins placement of the displayed authored settlement project.", "determinism": "Action identity is stable and independent of physical input.", "documentation": { "cost": "One bounded package action callback.", "examples": [ "ui.button(\"Place Project\", \"ui.action.settlement.placement-begin\", \"Preview this project\", 1)" ], "history": [ "1.19.0: Construction placement mode added for Phase 19Q9E." ], "id": "ui.action.settlement.placement-begin", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.ghost", "world.construction.placement-preview", "ui.action.settlement.designate" ], "returns": "No gameplay value until a separate designation action submits the existing command.", "signature": "ui.action.settlement.placement-begin", "usage": "Begin package-owned construction placement for the displayed authored project and close the settlement sheet so the world preview remains visible." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.settlement.placement-begin", "introduced": { "display": "1.9.0", "major": 1, "minor": 9, "patch": 0 }, "kind": "action", "name": "settlement.placement-begin", "namespace": "ui.action.settlement", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the package action callback; gameplay requests still use commands.", "signature": "ui.action.settlement.placement-begin", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.settlement.placement-begin.html" }, { "authority": "presentation", "availability": "Phase 19Q9E spatial interface", "deprecated": null, "description": "Cancels the current construction placement preview.", "determinism": "Action identity is stable and independent of physical input.", "documentation": { "cost": "One bounded package action callback.", "examples": [ "ui.button(\"Cancel\", \"ui.action.settlement.placement-cancel\", \"Cancel placement\", 1)" ], "history": [ "1.19.0: Placement cancellation added for Phase 19Q9E." ], "id": "ui.action.settlement.placement-cancel", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.action.settlement.placement-begin", "ui.intent.ghost" ], "returns": "No gameplay value.", "signature": "ui.action.settlement.placement-cancel", "usage": "Cancel package-owned construction placement and clear the detached ghost without submitting a gameplay command." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.settlement.placement-cancel", "introduced": { "display": "1.9.0", "major": 1, "minor": 9, "patch": 0 }, "kind": "action", "name": "settlement.placement-cancel", "namespace": "ui.action.settlement", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the package action callback; gameplay requests still use commands.", "signature": "ui.action.settlement.placement-cancel", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.settlement.placement-cancel.html" }, { "authority": "presentation", "availability": "Phase 16D player direction", "deprecated": null, "description": "Moves the construction cursor one World-grid cell east.", "determinism": "Action identity is stable and independent of physical input.", "documentation": { "cost": "One bounded package action.", "examples": [ "ui.button(\"East\", \"ui.action.settlement.placement-east\", \"Move placement east\", 1)" ], "history": [ "1.5.0: Standard placement cursor action added." ], "id": "ui.action.settlement.placement-east", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.action.settlement", "ui.action.settlement.designate" ], "returns": "No gameplay value; updates standard-interface presentation state.", "signature": "ui.action.settlement.placement-east", "usage": "Move the package-local building placement cursor one World-grid cell east." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.settlement.placement-east", "introduced": { "display": "1.5.0", "major": 1, "minor": 5, "patch": 0 }, "kind": "action", "name": "settlement.placement-east", "namespace": "ui.action.settlement", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the package action callback; gameplay requests still use commands.", "signature": "ui.action.settlement.placement-east", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.settlement.placement-east.html" }, { "authority": "presentation", "availability": "Phase 16D player direction", "deprecated": null, "description": "Moves the construction cursor one World-grid cell north.", "determinism": "Action identity is stable and independent of physical input.", "documentation": { "cost": "One bounded package action.", "examples": [ "ui.button(\"North\", \"ui.action.settlement.placement-north\", \"Move placement north\", 1)" ], "history": [ "1.5.0: Standard placement cursor action added." ], "id": "ui.action.settlement.placement-north", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.action.settlement", "ui.action.settlement.designate" ], "returns": "No gameplay value; updates standard-interface presentation state.", "signature": "ui.action.settlement.placement-north", "usage": "Move the package-local building placement cursor one World-grid cell north." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.settlement.placement-north", "introduced": { "display": "1.5.0", "major": 1, "minor": 5, "patch": 0 }, "kind": "action", "name": "settlement.placement-north", "namespace": "ui.action.settlement", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the package action callback; gameplay requests still use commands.", "signature": "ui.action.settlement.placement-north", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.settlement.placement-north.html" }, { "authority": "presentation", "availability": "Phase 19Q9E spatial interface", "deprecated": null, "description": "Rotates the current construction placement preview clockwise.", "determinism": "Action identity is stable and independent of physical input.", "documentation": { "cost": "One bounded package action callback and one later preview query.", "examples": [ "ui.button(\"Rotate\", \"ui.action.settlement.placement-rotate\", \"Rotate placement\", 1)" ], "history": [ "1.19.0: Placement rotation added for Phase 19Q9E." ], "id": "ui.action.settlement.placement-rotate", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [], "related": [ "world.construction.placement-preview", "command.construction.designate" ], "returns": "No gameplay value until designation.", "signature": "ui.action.settlement.placement-rotate", "usage": "Rotate the package-owned construction preview clockwise through the four orientations before validation and designation." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.settlement.placement-rotate", "introduced": { "display": "1.9.0", "major": 1, "minor": 9, "patch": 0 }, "kind": "action", "name": "settlement.placement-rotate", "namespace": "ui.action.settlement", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the package action callback; gameplay requests still use commands.", "signature": "ui.action.settlement.placement-rotate", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.settlement.placement-rotate.html" }, { "authority": "presentation", "availability": "Phase 16D player direction", "deprecated": null, "description": "Moves the construction cursor one World-grid cell south.", "determinism": "Action identity is stable and independent of physical input.", "documentation": { "cost": "One bounded package action.", "examples": [ "ui.button(\"South\", \"ui.action.settlement.placement-south\", \"Move placement south\", 1)" ], "history": [ "1.5.0: Standard placement cursor action added." ], "id": "ui.action.settlement.placement-south", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.action.settlement", "ui.action.settlement.designate" ], "returns": "No gameplay value; updates standard-interface presentation state.", "signature": "ui.action.settlement.placement-south", "usage": "Move the package-local building placement cursor one World-grid cell south." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.settlement.placement-south", "introduced": { "display": "1.5.0", "major": 1, "minor": 5, "patch": 0 }, "kind": "action", "name": "settlement.placement-south", "namespace": "ui.action.settlement", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the package action callback; gameplay requests still use commands.", "signature": "ui.action.settlement.placement-south", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.settlement.placement-south.html" }, { "authority": "presentation", "availability": "Phase 16D player direction", "deprecated": null, "description": "Moves the construction cursor one World-grid cell west.", "determinism": "Action identity is stable and independent of physical input.", "documentation": { "cost": "One bounded package action.", "examples": [ "ui.button(\"West\", \"ui.action.settlement.placement-west\", \"Move placement west\", 1)" ], "history": [ "1.5.0: Standard placement cursor action added." ], "id": "ui.action.settlement.placement-west", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.action.settlement", "ui.action.settlement.designate" ], "returns": "No gameplay value; updates standard-interface presentation state.", "signature": "ui.action.settlement.placement-west", "usage": "Move the package-local building placement cursor one World-grid cell west." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.settlement.placement-west", "introduced": { "display": "1.5.0", "major": 1, "minor": 5, "patch": 0 }, "kind": "action", "name": "settlement.placement-west", "namespace": "ui.action.settlement", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the package action callback; gameplay requests still use commands.", "signature": "ui.action.settlement.placement-west", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.settlement.placement-west.html" }, { "authority": "presentation", "availability": "Phase 16D player direction", "deprecated": null, "description": "Selects the next authored settlement project.", "determinism": "Action identity is stable and independent of physical input.", "documentation": { "cost": "One bounded package action.", "examples": [ "ui.button(\"Next\", \"ui.action.settlement.project-next\", \"Show next building\", 1)" ], "history": [ "1.5.0: Standard project browsing action added." ], "id": "ui.action.settlement.project-next", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.action.settlement", "world.project.alternatives" ], "returns": "No gameplay value; updates standard-interface presentation state.", "signature": "ui.action.settlement.project-next", "usage": "Show the next authored settlement building alternative in stable order." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.settlement.project-next", "introduced": { "display": "1.5.0", "major": 1, "minor": 5, "patch": 0 }, "kind": "action", "name": "settlement.project-next", "namespace": "ui.action.settlement", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the package action callback; gameplay requests still use commands.", "signature": "ui.action.settlement.project-next", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.settlement.project-next.html" }, { "authority": "presentation", "availability": "Phase 16D player direction", "deprecated": null, "description": "Selects the previous authored settlement project.", "determinism": "Action identity is stable and independent of physical input.", "documentation": { "cost": "One bounded package action.", "examples": [ "ui.button(\"Previous\", \"ui.action.settlement.project-previous\", \"Show previous building\", 1)" ], "history": [ "1.5.0: Standard project browsing action added." ], "id": "ui.action.settlement.project-previous", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.action.settlement", "world.project.alternatives" ], "returns": "No gameplay value; updates standard-interface presentation state.", "signature": "ui.action.settlement.project-previous", "usage": "Show the previous authored settlement building alternative in stable order." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.settlement.project-previous", "introduced": { "display": "1.5.0", "major": 1, "minor": 5, "patch": 0 }, "kind": "action", "name": "settlement.project-previous", "namespace": "ui.action.settlement", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the package action callback; gameplay requests still use commands.", "signature": "ui.action.settlement.project-previous", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.settlement.project-previous.html" }, { "authority": "presentation", "availability": "Phase 19Q9D settlement sheet", "deprecated": null, "description": "Selects one stable settlement sheet tab.", "determinism": "Action identity is stable and independent of physical input.", "documentation": { "cost": "One bounded package action callback.", "examples": [ "ui.tabs(\"ui.action.settlement.select-tab\", settlement_tabs, active_tab)" ], "history": [ "1.19.0: Settlement tab selection action added for Phase 19Q9D." ], "id": "ui.action.settlement.select-tab", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.tabs", "lifecycle.handle-action", "ui.layout.sheet" ], "returns": "No gameplay value. The package retains only the active tab index.", "signature": "ui.action.settlement.select-tab", "usage": "Select one of the six stable settlement overview tabs using the activation row_id." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.settlement.select-tab", "introduced": { "display": "1.9.0", "major": 1, "minor": 9, "patch": 0 }, "kind": "action", "name": "settlement.select-tab", "namespace": "ui.action.settlement", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the package action callback; gameplay requests still use commands.", "signature": "ui.action.settlement.select-tab", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.settlement.select-tab.html" }, { "authority": "presentation", "availability": "runtime API 1", "deprecated": null, "description": "Logical actions emitted by bounded spatial interface surfaces.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Namespace lookup is constant-time.", "examples": [ "-- Handle minimap activation through ui.action.surface.minimap-select." ], "history": [ "1.19.0: Spatial surface action namespace added for Phase 19Q9E." ], "id": "ui.action.surface", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.spatial-surface", "ui.action.surface.minimap-select" ], "returns": "The registered spatial-surface action contracts.", "signature": "namespace ui.action.surface", "usage": "Use this namespace for stable logical actions emitted by bounded spatial UI surfaces. The namespace itself does not read or mutate gameplay state." }, "errors": [], "fields": [], "id": "ui.action.surface", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "namespace", "name": "Spatial surface actions", "namespace": "ui.action.surface", "owner": "controls.ControlState", "replacement": null, "side_effects": "none", "signature": "namespace ui.action.surface", "source_location": "src/app/script_api_catalog.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.surface.html" }, { "authority": "presentation", "availability": "Phase 19Q9E spatial interface", "deprecated": null, "description": "Selects one stable World-grid position from the minimap.", "determinism": "Action identity is stable and independent of physical input.", "documentation": { "cost": "One bounded package action callback and one camera intent.", "examples": [ "function handle_action(action_id, row_id)\n if action_id == \"ui.action.surface.minimap-select\" then\n local x, y = string.match(row_id, \"^(-?%d+),(-?%d+)$\")\n end\nend" ], "history": [ "1.19.0: Minimap spatial activation added for Phase 19Q9E." ], "id": "ui.action.surface.minimap-select", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.action.surface", "ui.spatial-surface", "ui.pan-camera" ], "returns": "No gameplay value.", "signature": "ui.action.surface.minimap-select", "usage": "Receive a minimap-selected World cell as row_id and retain a transient camera-centering target for the next composition." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.surface.minimap-select", "introduced": { "display": "1.9.0", "major": 1, "minor": 9, "patch": 0 }, "kind": "action", "name": "surface.minimap-select", "namespace": "ui.action.surface", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the package action callback; gameplay requests still use commands.", "signature": "ui.action.surface.minimap-select", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.surface.minimap-select.html" }, { "authority": "presentation", "availability": "runtime API 1", "deprecated": null, "description": "Logical actions used by the first-party development tuning panel.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Constant action dispatch followed by a bounded restricted command submission.", "examples": [ "-- The host dispatches the selected tuning-bench action to handle_action." ], "history": [ "1.1.0: Development Tuning Bench action namespace added." ], "id": "ui.action.tuning-bench", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.action.tuning-bench.movement-1400", "ui.action.tuning-bench.construction-020", "ui.action.tuning-bench.time-100", "ui.action.tuning-bench.fps-060" ], "returns": "Logical action identities independent of mouse, keyboard, or controller bindings.", "signature": "namespace ui.action.tuning-bench", "usage": "Use these stable actions only through the first-party Development Tuning Bench callback." }, "errors": [], "fields": [], "id": "ui.action.tuning-bench", "introduced": { "display": "1.1.0", "major": 1, "minor": 1, "patch": 0 }, "kind": "namespace", "name": "Tuning bench actions", "namespace": "ui.action.tuning-bench", "owner": "controls.ControlState", "replacement": null, "side_effects": "none", "signature": "namespace ui.action.tuning-bench", "source_location": "src/app/script_api_catalog.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.tuning-bench.html" }, { "authority": "presentation", "availability": "Phase 16 capacity-policy development package", "deprecated": null, "description": "Sets the per-container capacity limit to 25 percent above observed use.", "determinism": "Action identity is stable and independent of physical input.", "documentation": { "cost": "One action, query, and command.", "examples": [ "-- Invoke through a registered button." ], "history": [ "1.2.0: Container-capacity preset added." ], "id": "ui.action.tuning-bench.capacity-container-headroom", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [], "related": [ "restricted.capacity-policy.set-limit" ], "returns": "No direct return.", "signature": "ui.action.tuning-bench.capacity-container-headroom", "usage": "Request per-container headroom above observed use." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.tuning-bench.capacity-container-headroom", "introduced": { "display": "1.2.0", "major": 1, "minor": 2, "patch": 0 }, "kind": "action", "name": "tuning-bench.capacity-container-headroom", "namespace": "ui.action.tuning-bench", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the package callback; capacity changes still use restricted commands.", "signature": "ui.action.tuning-bench.capacity-container-headroom", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.tuning-bench.capacity-container-headroom.html" }, { "authority": "presentation", "availability": "Phase 16 capacity-policy development package", "deprecated": null, "description": "Sets the live-population limit to 25 percent above observed use.", "determinism": "Action identity is stable and independent of physical input.", "documentation": { "cost": "One action, query, and command.", "examples": [ "-- Invoke through a registered button." ], "history": [ "1.2.0: Population-capacity preset added." ], "id": "ui.action.tuning-bench.capacity-population-headroom", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [], "related": [ "restricted.capacity-policy.set-limit" ], "returns": "No direct return.", "signature": "ui.action.tuning-bench.capacity-population-headroom", "usage": "Request population headroom above observed use." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.tuning-bench.capacity-population-headroom", "introduced": { "display": "1.2.0", "major": 1, "minor": 2, "patch": 0 }, "kind": "action", "name": "tuning-bench.capacity-population-headroom", "namespace": "ui.action.tuning-bench", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the package callback; capacity changes still use restricted commands.", "signature": "ui.action.tuning-bench.capacity-population-headroom", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.tuning-bench.capacity-population-headroom.html" }, { "authority": "presentation", "availability": "Phase 16 capacity-policy development package", "deprecated": null, "description": "Sets the aggregate resource limit to 25 percent above observed use.", "determinism": "Action identity is stable and independent of physical input.", "documentation": { "cost": "One action, query, and command.", "examples": [ "-- Invoke through a registered button." ], "history": [ "1.2.0: Resource-capacity preset added." ], "id": "ui.action.tuning-bench.capacity-resource-headroom", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [], "related": [ "restricted.capacity-policy.set-limit" ], "returns": "No direct return.", "signature": "ui.action.tuning-bench.capacity-resource-headroom", "usage": "Request aggregate resource headroom above observed use." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.tuning-bench.capacity-resource-headroom", "introduced": { "display": "1.2.0", "major": 1, "minor": 2, "patch": 0 }, "kind": "action", "name": "tuning-bench.capacity-resource-headroom", "namespace": "ui.action.tuning-bench", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the package callback; capacity changes still use restricted commands.", "signature": "ui.action.tuning-bench.capacity-resource-headroom", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.tuning-bench.capacity-resource-headroom.html" }, { "authority": "presentation", "availability": "Phase 16 capacity-policy development package", "deprecated": null, "description": "Sets aggregate storage capacity to 25 percent above observed use.", "determinism": "Action identity is stable and independent of physical input.", "documentation": { "cost": "One action, query, and command.", "examples": [ "-- Invoke through a registered button." ], "history": [ "1.2.0: Storage-capacity preset added." ], "id": "ui.action.tuning-bench.capacity-storage-headroom", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [], "related": [ "restricted.capacity-policy.set-limit" ], "returns": "No direct return.", "signature": "ui.action.tuning-bench.capacity-storage-headroom", "usage": "Request aggregate storage headroom above observed use." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.tuning-bench.capacity-storage-headroom", "introduced": { "display": "1.2.0", "major": 1, "minor": 2, "patch": 0 }, "kind": "action", "name": "tuning-bench.capacity-storage-headroom", "namespace": "ui.action.tuning-bench", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the package callback; capacity changes still use restricted commands.", "signature": "ui.action.tuning-bench.capacity-storage-headroom", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.tuning-bench.capacity-storage-headroom.html" }, { "authority": "presentation", "availability": "Phase 16 tuning addendum development package", "deprecated": null, "description": "Sets base construction throughput to 10 work units per second.", "determinism": "Action identity is stable and independent of physical input.", "documentation": { "cost": "One action callback and one restricted tuning request.", "examples": [ "ui.button(\"10 work/s\", \"ui.action.tuning-bench.construction-010\", \"Set 10 construction work units per second\")" ], "history": [ "1.1.0: Development construction-throughput tuning preset added." ], "id": "ui.action.tuning-bench.construction-010", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [], "related": [ "restricted.tuning.set-value", "ui.action.tuning-bench", "world.construction.progress" ], "returns": "A logical action delivered to the owning package callback.", "signature": "ui.action.tuning-bench.construction-010", "usage": "Select the 10 work-units-per-second base construction preset in the Development Tuning Bench." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.tuning-bench.construction-010", "introduced": { "display": "1.1.0", "major": 1, "minor": 1, "patch": 0 }, "kind": "action", "name": "tuning-bench.construction-010", "namespace": "ui.action.tuning-bench", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the package callback; runtime changes still use restricted commands.", "signature": "ui.action.tuning-bench.construction-010", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.tuning-bench.construction-010.html" }, { "authority": "presentation", "availability": "Phase 16 tuning addendum development package", "deprecated": null, "description": "Sets base construction throughput to 20 work units per second.", "determinism": "Action identity is stable and independent of physical input.", "documentation": { "cost": "One action callback and one restricted tuning request.", "examples": [ "ui.button(\"20 work/s\", \"ui.action.tuning-bench.construction-020\", \"Set 20 construction work units per second\")" ], "history": [ "1.1.0: Development construction-throughput tuning preset added." ], "id": "ui.action.tuning-bench.construction-020", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [], "related": [ "restricted.tuning.set-value", "ui.action.tuning-bench", "world.construction.progress" ], "returns": "A logical action delivered to the owning package callback.", "signature": "ui.action.tuning-bench.construction-020", "usage": "Select the default 20 work-units-per-second base construction preset in the Development Tuning Bench." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.tuning-bench.construction-020", "introduced": { "display": "1.1.0", "major": 1, "minor": 1, "patch": 0 }, "kind": "action", "name": "tuning-bench.construction-020", "namespace": "ui.action.tuning-bench", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the package callback; runtime changes still use restricted commands.", "signature": "ui.action.tuning-bench.construction-020", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.tuning-bench.construction-020.html" }, { "authority": "presentation", "availability": "Phase 16 tuning addendum development package", "deprecated": null, "description": "Sets base construction throughput to 40 work units per second.", "determinism": "Action identity is stable and independent of physical input.", "documentation": { "cost": "One action callback and one restricted tuning request.", "examples": [ "ui.button(\"40 work/s\", \"ui.action.tuning-bench.construction-040\", \"Set 40 construction work units per second\")" ], "history": [ "1.1.0: Development construction-throughput tuning preset added." ], "id": "ui.action.tuning-bench.construction-040", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [], "related": [ "restricted.tuning.set-value", "ui.action.tuning-bench", "world.construction.progress" ], "returns": "A logical action delivered to the owning package callback.", "signature": "ui.action.tuning-bench.construction-040", "usage": "Select the 40 work-units-per-second base construction preset in the Development Tuning Bench." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.tuning-bench.construction-040", "introduced": { "display": "1.1.0", "major": 1, "minor": 1, "patch": 0 }, "kind": "action", "name": "tuning-bench.construction-040", "namespace": "ui.action.tuning-bench", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the package callback; runtime changes still use restricted commands.", "signature": "ui.action.tuning-bench.construction-040", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.tuning-bench.construction-040.html" }, { "authority": "presentation", "availability": "Phase 16 tuning addendum development package", "deprecated": null, "description": "Sets the presentation frame target to 30 frames per second.", "determinism": "Action identity is stable and independent of physical input.", "documentation": { "cost": "One action callback and one restricted tuning request.", "examples": [ "ui.button(\"30 FPS\", \"ui.action.tuning-bench.fps-030\", \"Target 30 FPS\")" ], "history": [ "1.1.0: Development frame-target preset added." ], "id": "ui.action.tuning-bench.fps-030", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [], "related": [ "restricted.tuning.set-value", "ui.action.tuning-bench" ], "returns": "A logical action delivered to the owning package callback.", "signature": "ui.action.tuning-bench.fps-030", "usage": "Select the 30 FPS presentation target in the Development Tuning Bench." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.tuning-bench.fps-030", "introduced": { "display": "1.1.0", "major": 1, "minor": 1, "patch": 0 }, "kind": "action", "name": "tuning-bench.fps-030", "namespace": "ui.action.tuning-bench", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the package callback; runtime changes still use restricted commands.", "signature": "ui.action.tuning-bench.fps-030", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.tuning-bench.fps-030.html" }, { "authority": "presentation", "availability": "Phase 16 tuning addendum development package", "deprecated": null, "description": "Sets the presentation frame target to 60 frames per second.", "determinism": "Action identity is stable and independent of physical input.", "documentation": { "cost": "One action callback and one restricted tuning request.", "examples": [ "ui.button(\"60 FPS\", \"ui.action.tuning-bench.fps-060\", \"Target 60 FPS\")" ], "history": [ "1.1.0: Development frame-target preset added." ], "id": "ui.action.tuning-bench.fps-060", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [], "related": [ "restricted.tuning.set-value", "ui.action.tuning-bench" ], "returns": "A logical action delivered to the owning package callback.", "signature": "ui.action.tuning-bench.fps-060", "usage": "Select the 60 FPS presentation target in the Development Tuning Bench." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.tuning-bench.fps-060", "introduced": { "display": "1.1.0", "major": 1, "minor": 1, "patch": 0 }, "kind": "action", "name": "tuning-bench.fps-060", "namespace": "ui.action.tuning-bench", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the package callback; runtime changes still use restricted commands.", "signature": "ui.action.tuning-bench.fps-060", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.tuning-bench.fps-060.html" }, { "authority": "presentation", "availability": "Phase 16 tuning addendum development package", "deprecated": null, "description": "Sets the presentation frame target to 120 frames per second.", "determinism": "Action identity is stable and independent of physical input.", "documentation": { "cost": "One action callback and one restricted tuning request.", "examples": [ "ui.button(\"120 FPS\", \"ui.action.tuning-bench.fps-120\", \"Target 120 FPS\")" ], "history": [ "1.1.0: Development frame-target preset added." ], "id": "ui.action.tuning-bench.fps-120", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [], "related": [ "restricted.tuning.set-value", "ui.action.tuning-bench" ], "returns": "A logical action delivered to the owning package callback.", "signature": "ui.action.tuning-bench.fps-120", "usage": "Select the 120 FPS presentation target in the Development Tuning Bench." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.tuning-bench.fps-120", "introduced": { "display": "1.1.0", "major": 1, "minor": 1, "patch": 0 }, "kind": "action", "name": "tuning-bench.fps-120", "namespace": "ui.action.tuning-bench", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the package callback; runtime changes still use restricted commands.", "signature": "ui.action.tuning-bench.fps-120", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.tuning-bench.fps-120.html" }, { "authority": "presentation", "availability": "Phase 16 tuning addendum development package", "deprecated": null, "description": "Sets the base physical movement rate to 0.75 meters per second.", "determinism": "Action identity is stable and independent of physical input.", "documentation": { "cost": "One action callback and one restricted tuning request.", "examples": [ "ui.button(\"0.75 m/s\", \"ui.action.tuning-bench.movement-0750\", \"Set 0.75 m/s\")" ], "history": [ "1.1.0: Development physical-movement tuning preset added." ], "id": "ui.action.tuning-bench.movement-0750", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [], "related": [ "restricted.tuning.set-value", "ui.action.tuning-bench" ], "returns": "A logical action delivered to the owning package callback.", "signature": "ui.action.tuning-bench.movement-0750", "usage": "Select the 0.75 meters-per-second base physical movement preset in the Development Tuning Bench." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.tuning-bench.movement-0750", "introduced": { "display": "1.1.0", "major": 1, "minor": 1, "patch": 0 }, "kind": "action", "name": "tuning-bench.movement-0750", "namespace": "ui.action.tuning-bench", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the package callback; runtime changes still use restricted commands.", "signature": "ui.action.tuning-bench.movement-0750", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.tuning-bench.movement-0750.html" }, { "authority": "presentation", "availability": "Phase 16 tuning addendum development package", "deprecated": null, "description": "Sets the base physical movement rate to 1.40 meters per second.", "determinism": "Action identity is stable and independent of physical input.", "documentation": { "cost": "One action callback and one restricted tuning request.", "examples": [ "ui.button(\"1.40 m/s\", \"ui.action.tuning-bench.movement-1400\", \"Set 1.40 m/s\")" ], "history": [ "1.1.0: Development physical-movement tuning preset added." ], "id": "ui.action.tuning-bench.movement-1400", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [], "related": [ "restricted.tuning.set-value", "ui.action.tuning-bench" ], "returns": "A logical action delivered to the owning package callback.", "signature": "ui.action.tuning-bench.movement-1400", "usage": "Select the 1.40 meters-per-second base physical movement preset in the Development Tuning Bench." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.tuning-bench.movement-1400", "introduced": { "display": "1.1.0", "major": 1, "minor": 1, "patch": 0 }, "kind": "action", "name": "tuning-bench.movement-1400", "namespace": "ui.action.tuning-bench", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the package callback; runtime changes still use restricted commands.", "signature": "ui.action.tuning-bench.movement-1400", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.tuning-bench.movement-1400.html" }, { "authority": "presentation", "availability": "Phase 16 tuning addendum development package", "deprecated": null, "description": "Sets the base physical movement rate to 2.50 meters per second.", "determinism": "Action identity is stable and independent of physical input.", "documentation": { "cost": "One action callback and one restricted tuning request.", "examples": [ "ui.button(\"2.50 m/s\", \"ui.action.tuning-bench.movement-2500\", \"Set 2.50 m/s\")" ], "history": [ "1.1.0: Development physical-movement tuning preset added." ], "id": "ui.action.tuning-bench.movement-2500", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [], "related": [ "restricted.tuning.set-value", "ui.action.tuning-bench" ], "returns": "A logical action delivered to the owning package callback.", "signature": "ui.action.tuning-bench.movement-2500", "usage": "Select the 2.50 meters-per-second base physical movement preset in the Development Tuning Bench." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.tuning-bench.movement-2500", "introduced": { "display": "1.1.0", "major": 1, "minor": 1, "patch": 0 }, "kind": "action", "name": "tuning-bench.movement-2500", "namespace": "ui.action.tuning-bench", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the package callback; runtime changes still use restricted commands.", "signature": "ui.action.tuning-bench.movement-2500", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.tuning-bench.movement-2500.html" }, { "authority": "presentation", "availability": "Phase 17A world-indicator addendum", "deprecated": null, "description": "Hides the development resource-activity world indicators.", "determinism": "Action identity is stable and independent of physical input.", "documentation": { "cost": "One bounded package action and one indexed channel-state update.", "examples": [ "ui.button(\"Hide resource activity\", \"ui.action.tuning-bench.resource-indicators-hide\", \"Hide resource source status\", 1)" ], "history": [ "1.7.0: Tuning Bench resource-indicator hide action added." ], "id": "ui.action.tuning-bench.resource-indicators-hide", "manual_nodes": [ "phase.17", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.action.tuning-bench.resource-indicators-show", "world_indicators.set-visible" ], "returns": "No gameplay value; the development package changes host-owned presentation visibility.", "signature": "ui.action.tuning-bench.resource-indicators-hide", "usage": "Hide the development resource-activity indicators through the Tuning Bench." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.tuning-bench.resource-indicators-hide", "introduced": { "display": "1.7.0", "major": 1, "minor": 7, "patch": 0 }, "kind": "action", "name": "tuning-bench.resource-indicators-hide", "namespace": "ui.action.tuning-bench", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the development package presentation callback.", "signature": "ui.action.tuning-bench.resource-indicators-hide", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.tuning-bench.resource-indicators-hide.html" }, { "authority": "presentation", "availability": "Phase 17A world-indicator addendum", "deprecated": null, "description": "Shows the development resource-activity world indicators.", "determinism": "Action identity is stable and independent of physical input.", "documentation": { "cost": "One bounded package action and one indexed channel-state update.", "examples": [ "ui.button(\"Show resource activity\", \"ui.action.tuning-bench.resource-indicators-show\", \"Show resource source status\", 1)" ], "history": [ "1.7.0: Tuning Bench resource-indicator show action added." ], "id": "ui.action.tuning-bench.resource-indicators-show", "manual_nodes": [ "phase.17", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.action.tuning-bench.resource-indicators-hide", "world_indicators.set-visible" ], "returns": "No gameplay value; the development package changes host-owned presentation visibility.", "signature": "ui.action.tuning-bench.resource-indicators-show", "usage": "Show the development resource-activity indicators through the Tuning Bench." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.tuning-bench.resource-indicators-show", "introduced": { "display": "1.7.0", "major": 1, "minor": 7, "patch": 0 }, "kind": "action", "name": "tuning-bench.resource-indicators-show", "namespace": "ui.action.tuning-bench", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the development package presentation callback.", "signature": "ui.action.tuning-bench.resource-indicators-show", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.tuning-bench.resource-indicators-show.html" }, { "authority": "presentation", "availability": "Phase 16 tuning addendum development package", "deprecated": null, "description": "Sets simulation wall-clock pace to 0.5x.", "determinism": "Action identity is stable and independent of physical input.", "documentation": { "cost": "One action callback and one restricted tuning request.", "examples": [ "ui.button(\"0.5x\", \"ui.action.tuning-bench.time-050\", \"Half simulation pace\")" ], "history": [ "1.1.0: Development tuning preset added." ], "id": "ui.action.tuning-bench.time-050", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [], "related": [ "restricted.tuning.set-value", "ui.action.tuning-bench" ], "returns": "A logical action delivered to the owning package callback.", "signature": "ui.action.tuning-bench.time-050", "usage": "Select the 0.5x simulation wall-clock pace preset in the Development Tuning Bench." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.tuning-bench.time-050", "introduced": { "display": "1.1.0", "major": 1, "minor": 1, "patch": 0 }, "kind": "action", "name": "tuning-bench.time-050", "namespace": "ui.action.tuning-bench", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the package callback; runtime changes still use restricted commands.", "signature": "ui.action.tuning-bench.time-050", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.tuning-bench.time-050.html" }, { "authority": "presentation", "availability": "Phase 16 tuning addendum development package", "deprecated": null, "description": "Sets simulation wall-clock pace to 1x.", "determinism": "Action identity is stable and independent of physical input.", "documentation": { "cost": "One action callback and one restricted tuning request.", "examples": [ "ui.button(\"1x\", \"ui.action.tuning-bench.time-100\", \"Normal simulation pace\")" ], "history": [ "1.1.0: Development tuning preset added." ], "id": "ui.action.tuning-bench.time-100", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [], "related": [ "restricted.tuning.set-value", "ui.action.tuning-bench" ], "returns": "A logical action delivered to the owning package callback.", "signature": "ui.action.tuning-bench.time-100", "usage": "Select the normal 1x simulation wall-clock pace preset in the Development Tuning Bench." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.tuning-bench.time-100", "introduced": { "display": "1.1.0", "major": 1, "minor": 1, "patch": 0 }, "kind": "action", "name": "tuning-bench.time-100", "namespace": "ui.action.tuning-bench", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the package callback; runtime changes still use restricted commands.", "signature": "ui.action.tuning-bench.time-100", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.tuning-bench.time-100.html" }, { "authority": "presentation", "availability": "Phase 16 tuning addendum development package", "deprecated": null, "description": "Sets simulation wall-clock pace to 2x.", "determinism": "Action identity is stable and independent of physical input.", "documentation": { "cost": "One action callback and one restricted tuning request.", "examples": [ "ui.button(\"2x\", \"ui.action.tuning-bench.time-200\", \"Double simulation pace\")" ], "history": [ "1.1.0: Development tuning preset added." ], "id": "ui.action.tuning-bench.time-200", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [], "related": [ "restricted.tuning.set-value", "ui.action.tuning-bench" ], "returns": "A logical action delivered to the owning package callback.", "signature": "ui.action.tuning-bench.time-200", "usage": "Select the 2x simulation wall-clock pace preset in the Development Tuning Bench." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.tuning-bench.time-200", "introduced": { "display": "1.1.0", "major": 1, "minor": 1, "patch": 0 }, "kind": "action", "name": "tuning-bench.time-200", "namespace": "ui.action.tuning-bench", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the package callback; runtime changes still use restricted commands.", "signature": "ui.action.tuning-bench.time-200", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.tuning-bench.time-200.html" }, { "authority": "presentation", "availability": "runtime API 1", "deprecated": null, "description": "Logical actions used by standard work direction.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Constant-time action lookup.", "examples": [ "-- Bind controls to ui.action.work.assign or ui.action.work.priority-high." ], "history": [ "1.5.0: Standard Work direction actions added for Phase 16D." ], "id": "ui.action.work", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.action.work.assign", "ui.action.work.cancel", "lifecycle.handle-action" ], "returns": "The registered Work action IDs.", "signature": "namespace ui.action.work", "usage": "Use these first-party standard-interface actions to browse visible work, assign it, change priority, or cancel the current assignment." }, "errors": [], "fields": [], "id": "ui.action.work", "introduced": { "display": "1.5.0", "major": 1, "minor": 5, "patch": 0 }, "kind": "namespace", "name": "Work interface actions", "namespace": "ui.action.work", "owner": "controls.ControlState", "replacement": null, "side_effects": "none", "signature": "namespace ui.action.work", "source_location": "src/app/script_api_catalog.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.work.html" }, { "authority": "presentation", "availability": "Phase 16D player direction", "deprecated": null, "description": "Requests assignment of the selected actor to the displayed Work target.", "determinism": "Action identity is stable and independent of physical input.", "documentation": { "cost": "One action callback, bounded detached reads, and one command submission.", "examples": [ "ui.button(\"Assign\", \"ui.action.work.assign\", \"Assign this work\", 1)" ], "history": [ "1.5.0: Standard Work assignment action added." ], "id": "ui.action.work.assign", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.action.work", "command.work.assign" ], "returns": "No direct value; the package handler submits command.work.assign.", "signature": "ui.action.work.assign", "usage": "Assign the displayed work target to the selected villager through the normal Work command." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.work.assign", "introduced": { "display": "1.5.0", "major": 1, "minor": 5, "patch": 0 }, "kind": "action", "name": "work.assign", "namespace": "ui.action.work", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the package action callback; gameplay requests still use commands.", "signature": "ui.action.work.assign", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.work.assign.html" }, { "authority": "presentation", "availability": "Phase 16D player direction", "deprecated": null, "description": "Requests cancellation of the selected actor's current Work assignment.", "determinism": "Action identity is stable and independent of physical input.", "documentation": { "cost": "One action callback, one indexed query, and one command submission.", "examples": [ "ui.button(\"Cancel\", \"ui.action.work.cancel\", \"Cancel this assignment\", 1)" ], "history": [ "1.5.0: Standard Work cancellation action added." ], "id": "ui.action.work.cancel", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.action.work", "command.work.cancel" ], "returns": "No direct value; the package handler submits command.work.cancel.", "signature": "ui.action.work.cancel", "usage": "Cancel the selected villager's current live player assignment." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.work.cancel", "introduced": { "display": "1.5.0", "major": 1, "minor": 5, "patch": 0 }, "kind": "action", "name": "work.cancel", "namespace": "ui.action.work", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the package action callback; gameplay requests still use commands.", "signature": "ui.action.work.cancel", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.work.cancel.html" }, { "authority": "presentation", "availability": "Phase 16D player direction", "deprecated": null, "description": "Selects the next actionable Work target.", "determinism": "Action identity is stable and independent of physical input.", "documentation": { "cost": "One bounded package action.", "examples": [ "ui.button(\"Next\", \"ui.action.work.next\", \"Show next work target\", 1)" ], "history": [ "1.5.0: Standard Work browsing action added." ], "id": "ui.action.work.next", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.action.work", "world.work.targets" ], "returns": "No gameplay value; updates standard-interface presentation state.", "signature": "ui.action.work.next", "usage": "Show the next visible work target in stable order." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.work.next", "introduced": { "display": "1.5.0", "major": 1, "minor": 5, "patch": 0 }, "kind": "action", "name": "work.next", "namespace": "ui.action.work", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the package action callback; gameplay requests still use commands.", "signature": "ui.action.work.next", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.work.next.html" }, { "authority": "presentation", "availability": "Phase 16D player direction", "deprecated": null, "description": "Selects the previous actionable Work target.", "determinism": "Action identity is stable and independent of physical input.", "documentation": { "cost": "One bounded package action.", "examples": [ "ui.button(\"Previous\", \"ui.action.work.previous\", \"Show previous work target\", 1)" ], "history": [ "1.5.0: Standard Work browsing action added." ], "id": "ui.action.work.previous", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.action.work", "world.work.targets" ], "returns": "No gameplay value; updates standard-interface presentation state.", "signature": "ui.action.work.previous", "usage": "Show the previous visible work target in stable order." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.work.previous", "introduced": { "display": "1.5.0", "major": 1, "minor": 5, "patch": 0 }, "kind": "action", "name": "work.previous", "namespace": "ui.action.work", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the package action callback; gameplay requests still use commands.", "signature": "ui.action.work.previous", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.work.previous.html" }, { "authority": "presentation", "availability": "Phase 16D player direction", "deprecated": null, "description": "Raises the displayed Work target's player priority.", "determinism": "Action identity is stable and independent of physical input.", "documentation": { "cost": "One action callback and one command submission.", "examples": [ "ui.button(\"High Priority\", \"ui.action.work.priority-high\", \"Raise work priority\", 1)" ], "history": [ "1.5.0: Standard high-priority action added." ], "id": "ui.action.work.priority-high", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.action.work", "command.work.set-priority" ], "returns": "No direct value; the package handler submits command.work.set-priority.", "signature": "ui.action.work.priority-high", "usage": "Set the displayed Work target's durable player priority to the high preset." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.work.priority-high", "introduced": { "display": "1.5.0", "major": 1, "minor": 5, "patch": 0 }, "kind": "action", "name": "work.priority-high", "namespace": "ui.action.work", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the package action callback; gameplay requests still use commands.", "signature": "ui.action.work.priority-high", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.work.priority-high.html" }, { "authority": "presentation", "availability": "Phase 16D player direction", "deprecated": null, "description": "Returns the displayed Work target to normal player priority.", "determinism": "Action identity is stable and independent of physical input.", "documentation": { "cost": "One action callback and one command submission.", "examples": [ "ui.button(\"Normal Priority\", \"ui.action.work.priority-normal\", \"Clear work priority\", 1)" ], "history": [ "1.5.0: Standard neutral-priority action added." ], "id": "ui.action.work.priority-normal", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.action.work", "command.work.set-priority" ], "returns": "No direct value; the package handler submits command.work.set-priority with the neutral preset.", "signature": "ui.action.work.priority-normal", "usage": "Clear the displayed Work target's durable player-priority contribution." }, "errors": [ "error.invalid-action" ], "fields": [], "id": "ui.action.work.priority-normal", "introduced": { "display": "1.5.0", "major": 1, "minor": 5, "patch": 0 }, "kind": "action", "name": "work.priority-normal", "namespace": "ui.action.work", "owner": "controls.ControlState", "replacement": null, "side_effects": "Invokes the package action callback; gameplay requests still use commands.", "signature": "ui.action.work.priority-normal", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.action.work.priority-normal.html" }, { "authority": "presentation", "availability": "Phase 14 package callbacks", "deprecated": null, "description": "Begins one bounded backend-neutral semantic panel.", "determinism": "Host-created package identity and per-callback budgets.", "documentation": { "cost": "Counts against the package composition instruction and surface work budgets; it does not traverse simulation ownership.", "examples": [ "ui.begin_panel({id = \"addon.status\", title = \"Status\", anchor = \"top-right\", x = 24, y = 72, width = 300, height = 180, movable = true, semantic_label = \"Addon status\", semantic_role = \"status\"})" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "ui.begin-panel", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [ "panel_contract: table containing stable id, title, semantic metadata, and either anchored floating geometry or dock, thickness, and optional reserves_space fields." ], "related": [ "ui" ], "returns": "No gameplay value. The call appends or updates semantic presentation state for the current composition pass.", "signature": "ui.begin_panel(panel_contract)", "usage": "Call during composition to append validated semantic presentation state. The panel ID must be unique and stable inside the calling package; the host combines package and local IDs for backend window identity. Floating panels may be movable. A docked panel names one fixed edge and may reserve that space from the world viewport. This function cannot mutate simulation owners." }, "errors": [], "fields": [], "id": "ui.begin-panel", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "function", "name": "begin_panel", "namespace": "ui", "owner": "app.ScriptPackageHost", "replacement": null, "side_effects": "records bounded detached presentation intent", "signature": "ui.begin_panel(panel_contract)", "source_location": "src/app/script_package_host.cpp", "timing": "composition", "units": null, "url": "/api/v1/symbols/ui.begin-panel.html" }, { "authority": "presentation", "availability": "Phase 14 package callbacks", "deprecated": null, "description": "Begins one non-nested horizontal widget group.", "determinism": "Host-created package identity and per-callback budgets.", "documentation": { "cost": "Counts as one widget against the package composition budget.", "examples": [ "ui.begin_row_group()\nui.stat(tostring(settlement.actor_count), \"Residents\")\nui.spacer()\nui.text(\"State\", \"Running\")\nui.end_row_group()" ], "history": [ "1.19.0: Added for the Phase 19Q9 anchored player HUD." ], "id": "ui.begin-row-group", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.end-row-group", "ui.separator", "ui.spacer", "ui.stat", "ui.widget.row-group" ], "returns": "No gameplay value. The call appends one bounded structural presentation intent.", "signature": "ui.begin_row_group()", "usage": "Begin one horizontal widget group inside the current panel. Groups cannot nest and must be closed before the panel ends." }, "errors": [], "fields": [], "id": "ui.begin-row-group", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "function", "name": "begin_row_group", "namespace": "ui", "owner": "app.ScriptPackageHost", "replacement": null, "side_effects": "records bounded detached presentation intent", "signature": "ui.begin_row_group()", "source_location": "src/app/script_package_host.cpp", "timing": "composition", "units": null, "url": "/api/v1/symbols/ui.begin-row-group.html" }, { "authority": "presentation", "availability": "Phase 14 package callbacks", "deprecated": null, "description": "Records one semantic button bound to a logical action.", "determinism": "Host-created package identity and per-callback budgets.", "documentation": { "cost": "Counts against the package composition instruction and surface work budgets; it does not traverse simulation ownership.", "examples": [ "ui.button(\"Take Control\", \"ui.action.actor.take-control\", \"Directly control the selected villager\", 1)" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "ui.button", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [ "label: visible button text.", "action_id: registered logical action dispatched to handle_action.", "semantic_label: assistive description of the action.", "focus_order: optional deterministic keyboard order." ], "related": [ "ui" ], "returns": "No gameplay value. The call appends or updates semantic presentation state for the current composition pass.", "signature": "ui.button(label, action_id, semantic_label, focus_order?)", "usage": "Call during composition to append validated semantic presentation state. This function cannot mutate simulation owners." }, "errors": [], "fields": [], "id": "ui.button", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "function", "name": "button", "namespace": "ui", "owner": "app.ScriptPackageHost", "replacement": null, "side_effects": "records bounded detached presentation intent", "signature": "ui.button(label, action_id, semantic_label, focus_order?)", "source_location": "src/app/script_package_host.cpp", "timing": "composition", "units": null, "url": "/api/v1/symbols/ui.button.html" }, { "authority": "presentation", "availability": "Phase 14 package callbacks", "deprecated": null, "description": "Closes the current semantic panel.", "determinism": "Host-created package identity and per-callback budgets.", "documentation": { "cost": "Counts against the package composition instruction and surface work budgets; it does not traverse simulation ownership.", "examples": [ "ui.end_panel()" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "ui.end-panel", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui" ], "returns": "No gameplay value. The call appends or updates semantic presentation state for the current composition pass.", "signature": "ui.end_panel()", "usage": "Call during composition to append validated semantic presentation state. This function cannot mutate simulation owners." }, "errors": [], "fields": [], "id": "ui.end-panel", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "function", "name": "end_panel", "namespace": "ui", "owner": "app.ScriptPackageHost", "replacement": null, "side_effects": "records bounded detached presentation intent", "signature": "ui.end_panel()", "source_location": "src/app/script_package_host.cpp", "timing": "composition", "units": null, "url": "/api/v1/symbols/ui.end-panel.html" }, { "authority": "presentation", "availability": "Phase 14 package callbacks", "deprecated": null, "description": "Closes the current horizontal widget group.", "determinism": "Host-created package identity and per-callback budgets.", "documentation": { "cost": "Counts as one widget against the package composition budget.", "examples": [ "ui.begin_row_group()\nui.text(\"Project\", \"Workshop\")\nui.end_row_group()" ], "history": [ "1.19.0: Added for the Phase 19Q9 anchored player HUD." ], "id": "ui.end-row-group", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.begin-row-group", "ui.widget.row-group" ], "returns": "No gameplay value. The call appends one bounded structural presentation intent.", "signature": "ui.end_row_group()", "usage": "Close the current horizontal widget group before ending its panel." }, "errors": [], "fields": [], "id": "ui.end-row-group", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "function", "name": "end_row_group", "namespace": "ui", "owner": "app.ScriptPackageHost", "replacement": null, "side_effects": "records bounded detached presentation intent", "signature": "ui.end_row_group()", "source_location": "src/app/script_package_host.cpp", "timing": "composition", "units": null, "url": "/api/v1/symbols/ui.end-row-group.html" }, { "authority": "presentation", "availability": "Phase 14 package callbacks", "deprecated": null, "description": "Records one wrapped full-width explanation paragraph.", "determinism": "Host-created package identity and per-callback budgets.", "documentation": { "cost": "Counts as one widget and its text against the package composition budgets.", "examples": [ "ui.explain(\"The workshop is waiting for split logs before construction can resume.\")" ], "history": [ "1.19.0: Added wrapped explanation paragraphs for Phase 19Q9B." ], "id": "ui.explain", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [ "text: complete player-facing explanation." ], "related": [ "ui.widget.explain", "ui.list" ], "returns": "No gameplay value. The call appends one bounded explanation intent.", "signature": "ui.explain(text)", "usage": "Show one complete reason as a full-width wrapped paragraph inside the current panel. Use this for decision explanations and blockers that should not be clipped into a key-value row." }, "errors": [], "fields": [], "id": "ui.explain", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "function", "name": "explain", "namespace": "ui", "owner": "app.ScriptPackageHost", "replacement": null, "side_effects": "records bounded detached presentation intent", "signature": "ui.explain(text)", "source_location": "src/app/script_package_host.cpp", "timing": "composition", "units": null, "url": "/api/v1/symbols/ui.explain.html" }, { "authority": "presentation", "availability": "Phase 14 package callbacks", "deprecated": null, "description": "Records one optional placement-footprint ghost.", "determinism": "Host-created package identity and per-callback budgets.", "documentation": { "cost": "At most 64 outlined World cells during presentation.", "examples": [ "ui.ghost(8, 3, 2, 2, preview.valid, preview.detail)" ], "history": [ "1.19.0: Placement ghost intent added for Phase 19Q9E." ], "id": "ui.ghost", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [ "origin_x and origin_y: signed World-grid origin.", "width and height: positive footprint bounds with at most 64 cells total.", "valid: whether the preview is currently available.", "caption: bounded player-facing validation detail." ], "related": [ "ui.intent.ghost", "world.construction.placement-preview", "command.construction.designate" ], "returns": "No gameplay value. The call records one detached world-overlay intent.", "signature": "ui.ghost(origin_x, origin_y, width, height, valid, caption)", "usage": "Declare at most one bounded placement-footprint preview outside a panel. Render draws the footprint using valid or blocked presentation without designating construction." }, "errors": [], "fields": [], "id": "ui.ghost", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "function", "name": "ghost", "namespace": "ui", "owner": "app.ScriptPackageHost", "replacement": null, "side_effects": "records bounded detached presentation intent", "signature": "ui.ghost(origin_x, origin_y, width, height, valid, caption)", "source_location": "src/app/script_package_host.cpp", "timing": "composition", "units": null, "url": "/api/v1/symbols/ui.ghost.html" }, { "authority": "presentation", "availability": "runtime API 1", "deprecated": null, "description": "Bounded detached camera and world-overlay requests.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Namespace lookup is constant-time.", "examples": [ "-- Compose camera intent with ui.pan_camera and ghost intent with ui.ghost." ], "history": [ "1.19.0: Detached spatial intent namespace added for Phase 19Q9E." ], "id": "ui.intent", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.intent.camera", "ui.intent.ghost" ], "returns": "The registered detached presentation-intent contracts.", "signature": "namespace ui.intent", "usage": "Use the registered child contracts to inspect bounded detached camera and world-overlay intent. This namespace has no independent state or mutation authority." }, "errors": [], "fields": [], "id": "ui.intent", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "namespace", "name": "Interface presentation intents", "namespace": "ui.intent", "owner": "app.ScriptUiIntentBuffer", "replacement": null, "side_effects": "none", "signature": "namespace ui.intent", "source_location": "src/app/script_api_catalog.cpp", "timing": "composition", "units": null, "url": "/api/v1/symbols/ui.intent.html" }, { "authority": "presentation", "availability": "Phase 19Q9E", "deprecated": null, "description": "One optional request to center the Render-owned camera on a World cell.", "determinism": "At most one validated intent per composition.", "documentation": { "cost": "At most one record per composition.", "examples": [ "ui.pan_camera(target_x, target_y)" ], "history": [ "1.19.0: Camera intent contract added for Phase 19Q9E." ], "id": "ui.intent.camera", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.intent", "ui.pan-camera" ], "returns": "A constant-size detached camera intent.", "signature": "{ cell_x, cell_y, center }", "usage": "Represent one validated request to center the Render-owned camera. The composition buffer owns this detached value only for the current frame." }, "errors": [], "fields": [], "id": "ui.intent.camera", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "type", "name": "camera", "namespace": "ui.intent", "owner": "app.ScriptUiIntentBuffer", "replacement": null, "side_effects": "Render may center its camera after successful composition.", "signature": "{ cell_x, cell_y, center }", "source_location": "src/app/script_ui_intent.hpp", "timing": "composition", "units": "World-grid cells", "url": "/api/v1/symbols/ui.intent.camera.html" }, { "authority": "presentation", "availability": "Phase 19Q9E", "deprecated": null, "description": "One optional validated construction-footprint preview.", "determinism": "At most one validated intent per composition.", "documentation": { "cost": "At most one record and 64 rendered cells per composition.", "examples": [ "ui.ghost(x, y, width, height, preview.valid, preview.detail)" ], "history": [ "1.19.0: Placement ghost contract added for Phase 19Q9E." ], "id": "ui.intent.ghost", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.intent", "ui.ghost", "world.construction.placement-preview" ], "returns": "A bounded detached placement-ghost intent.", "signature": "{ origin_x, origin_y, width_cells, height_cells, valid, caption }", "usage": "Represent one validated placement footprint for Render. The record is presentation-only and has no save or construction authority." }, "errors": [], "fields": [], "id": "ui.intent.ghost", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "type", "name": "ghost", "namespace": "ui.intent", "owner": "app.ScriptUiIntentBuffer", "replacement": null, "side_effects": "Records detached presentation intent.", "signature": "{ origin_x, origin_y, width_cells, height_cells, valid, caption }", "source_location": "src/app/script_ui_intent.hpp", "timing": "composition", "units": "World-grid cells", "url": "/api/v1/symbols/ui.intent.ghost.html" }, { "authority": "presentation", "availability": "runtime API 1", "deprecated": null, "description": "Scale-aware semantic layout contracts.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Namespace lookup is constant-time and performs no owner work.", "examples": [ "-- Access documented members through ui.layout.anchored." ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "ui.layout", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.layout.anchored" ], "returns": "A stable namespace table containing only the documented child symbols available to this package origin.", "signature": "namespace ui.layout", "usage": "Use ui.layout only to reach its registered child contracts. The namespace itself performs no query, mutation, lifecycle transition, or drawing." }, "errors": [], "fields": [], "id": "ui.layout", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "namespace", "name": "Interface layout", "namespace": "ui.layout", "owner": "app.ScriptUiLayout", "replacement": null, "side_effects": "none", "signature": "namespace ui.layout", "source_location": "src/app/script_api_catalog.cpp", "timing": "composition", "units": null, "url": "/api/v1/symbols/ui.layout.html" }, { "authority": "presentation", "availability": "Phase 14G", "deprecated": null, "description": "Scale-aware layout with bounds and a semantic screen anchor.", "determinism": "Resolved from the current viewport without persisting physical pixels.", "documentation": { "cost": "Constant-size contract lookup or bounded retained-record access.", "examples": [ "local panel = {anchor = \"top-right\", x = 24, y = 72}" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "ui.layout.anchored", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.layout" ], "returns": "A stable type contract consumed by the interface composition host.", "signature": "top-left | top-right | bottom-left | bottom-right | center", "usage": "Use one registered anchor value in a panel contract; offsets remain inset distances from that anchor." }, "errors": [], "fields": [], "id": "ui.layout.anchored", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "type", "name": "anchored", "namespace": "ui.layout", "owner": "app.ScriptUiLayout", "replacement": null, "side_effects": "none", "signature": "top-left | top-right | bottom-left | bottom-right | center", "source_location": "src/app/script_ui_intent.hpp", "timing": "composition", "units": null, "url": "/api/v1/symbols/ui.layout.anchored.html" }, { "authority": "presentation", "availability": "Phase 19Q9F Empire view", "deprecated": null, "description": "Viewport-filling non-movable panel for a spatial surface behind frame panels.", "determinism": "Resolved from the current reserved world viewport.", "documentation": { "cost": "One panel and its bounded widgets against the normal composition budgets.", "examples": [ "ui.begin_panel({id = \"empire-map\", title = \"Regional map\", mode = \"canvas\", margin = 0})" ], "history": [ "1.19.0: Full-viewport canvas layout added for Phase 19Q9F." ], "id": "ui.layout.canvas", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.layout", "ui.spatial-surface", "ui.surface.kind" ], "returns": "A full-viewport presentation layout contract.", "signature": "mode = canvas", "usage": "Fill the current world viewport with one fixed script-owned presentation canvas. Use it for a regional map beneath movable inspectors; it does not reserve or mutate World state." }, "errors": [], "fields": [], "id": "ui.layout.canvas", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "type", "name": "canvas", "namespace": "ui.layout", "owner": "app.ScriptUiPanel", "replacement": null, "side_effects": "Records detached presentation intent.", "signature": "mode = canvas", "source_location": "src/app/script_ui_intent.hpp", "timing": "composition", "units": "reserved world viewport", "url": "/api/v1/symbols/ui.layout.canvas.html" }, { "authority": "presentation", "availability": "Phase 19Q9A", "deprecated": null, "description": "Fixed edge dock that may reserve world viewport space.", "determinism": "Declaration order determines edge stacking.", "documentation": { "cost": "Constant-size validation and declaration-order edge layout.", "examples": [ "ui.begin_panel({id = \"status\", title = \"Status\", dock = \"top\", thickness = 92, semantic_label = \"Village status\", semantic_role = \"status\"})" ], "history": [ "1.19.0: Added fixed edge docks and world viewport reservation." ], "id": "ui.layout.dock", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.begin-panel", "ui.layout" ], "returns": "A stable type contract consumed by the interface composition host.", "signature": "top | bottom | left | right", "usage": "Set panel_contract.dock to one registered edge and panel_contract.thickness to a finite value from 24 through 720 logical pixels. Docked panels are fixed. reserves_space defaults to true and removes the dock area from the world viewport." }, "errors": [], "fields": [], "id": "ui.layout.dock", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "type", "name": "dock", "namespace": "ui.layout", "owner": "app.ScriptUiDock", "replacement": null, "side_effects": "Records detached presentation intent.", "signature": "top | bottom | left | right", "source_location": "src/app/script_ui_intent.hpp", "timing": "composition", "units": "logical pixels at interface scale", "url": "/api/v1/symbols/ui.layout.dock.html" }, { "authority": "presentation", "availability": "Phase 19Q9D", "deprecated": null, "description": "Centered backdrop panel constrained by a bounded viewport margin.", "determinism": "Resolved from the current reserved world viewport.", "documentation": { "cost": "Constant-size validation and viewport-relative layout.", "examples": [ "ui.begin_panel({id = \"settlement\", title = \"Settlement\", mode = \"sheet\", margin = 160, semantic_label = \"Settlement overview\", semantic_role = \"region\"})" ], "history": [ "1.19.0: Added centered viewport sheets for Phase 19Q9D." ], "id": "ui.layout.sheet", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.begin-panel", "ui.tabs", "ui.layout.dock" ], "returns": "A stable layout contract consumed by the interface renderer.", "signature": "mode = sheet, margin = logical-pixels", "usage": "Set panel_contract.mode to sheet and provide a finite margin from 32 through 320 logical pixels. The renderer centers the sheet inside the reserved world viewport while leaving fixed docks live." }, "errors": [], "fields": [], "id": "ui.layout.sheet", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "type", "name": "sheet", "namespace": "ui.layout", "owner": "app.ScriptUiPanel", "replacement": null, "side_effects": "Records detached presentation intent.", "signature": "mode = sheet, margin = logical-pixels", "source_location": "src/app/script_ui_intent.hpp", "timing": "composition", "units": "logical pixels at interface scale", "url": "/api/v1/symbols/ui.layout.sheet.html" }, { "authority": "presentation", "availability": "Phase 14 package callbacks", "deprecated": null, "description": "Records one bounded selectable list with stable row identities.", "determinism": "Host-created package identity and per-callback budgets.", "documentation": { "cost": "The list and each row count against the bounded widget budget; row text counts against the text budget.", "examples": [ "ui.list(\"ui.action.work.select\", {{id = \"job:42\", label = \"Gather timber\", value = \"Ready\", selected = true}}, {visible_rows = 6})" ], "history": [ "1.19.0: Added stable selectable lists for Phase 19Q9B." ], "id": "ui.list", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [ "action_id: logical action dispatched when a row is selected.", "rows: ordered row tables containing unique id and label fields plus optional value, color, selected, and progress fields.", "options: optional table containing visible_rows." ], "related": [ "ui.widget.list", "ui.widget.list-row", "lifecycle.handle-action", "ui.explain" ], "returns": "No gameplay value. Selecting a row dispatches action_id and the row ID to lifecycle.handle-action.", "signature": "ui.list(action_id, rows, options?)", "usage": "Compose a scroll-bounded selectable list. Give every row a stable ID so selection remains meaningful when visible labels or detached values change." }, "errors": [], "fields": [], "id": "ui.list", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "function", "name": "list", "namespace": "ui", "owner": "app.ScriptPackageHost", "replacement": null, "side_effects": "records bounded detached presentation intent", "signature": "ui.list(action_id, rows, options?)", "source_location": "src/app/script_package_host.cpp", "timing": "composition", "units": null, "url": "/api/v1/symbols/ui.list.html" }, { "authority": "presentation", "availability": "Phase 14 package callbacks", "deprecated": null, "description": "Records one menu heading.", "determinism": "Host-created package identity and per-callback budgets.", "documentation": { "cost": "Counts against the package composition instruction and surface work budgets; it does not traverse simulation ownership.", "examples": [ "ui.menu(\"World\", \"Observe the settlement\")" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "ui.menu", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [ "label: menu or section label.", "state: optional visible state text." ], "related": [ "ui" ], "returns": "No gameplay value. The call appends or updates semantic presentation state for the current composition pass.", "signature": "ui.menu(label, state?)", "usage": "Call during composition to append validated semantic presentation state. This function cannot mutate simulation owners." }, "errors": [], "fields": [], "id": "ui.menu", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "function", "name": "menu", "namespace": "ui", "owner": "app.ScriptPackageHost", "replacement": null, "side_effects": "records bounded detached presentation intent", "signature": "ui.menu(label, state?)", "source_location": "src/app/script_package_host.cpp", "timing": "composition", "units": null, "url": "/api/v1/symbols/ui.menu.html" }, { "authority": "presentation", "availability": "Phase 14 package callbacks", "deprecated": null, "description": "Records one optional camera-centering intent.", "determinism": "Host-created package identity and per-callback budgets.", "documentation": { "cost": "Constant-size validation and one Render camera update.", "examples": [ "ui.pan_camera(12, -4)" ], "history": [ "1.19.0: Camera-centering presentation intent added for Phase 19Q9E." ], "id": "ui.pan-camera", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [ "cell_x: signed World-grid X coordinate.", "cell_y: signed World-grid Y coordinate." ], "related": [ "ui.intent.camera", "ui.spatial-surface" ], "returns": "No gameplay value. The call records one detached camera intent.", "signature": "ui.pan_camera(cell_x, cell_y)", "usage": "Declare at most one request outside a panel to center the Render-owned camera on a bounded World-cell coordinate. The request never changes simulation state." }, "errors": [], "fields": [], "id": "ui.pan-camera", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "function", "name": "pan_camera", "namespace": "ui", "owner": "app.ScriptPackageHost", "replacement": null, "side_effects": "centers the Render-owned camera", "signature": "ui.pan_camera(cell_x, cell_y)", "source_location": "src/app/script_package_host.cpp", "timing": "composition", "units": null, "url": "/api/v1/symbols/ui.pan-camera.html" }, { "authority": "presentation", "availability": "Phase 14 package callbacks", "deprecated": null, "description": "Records one bounded progress value.", "determinism": "Host-created package identity and per-callback budgets.", "documentation": { "cost": "Counts against the package composition instruction and surface work budgets; it does not traverse simulation ownership.", "examples": [ "ui.progress(\"Hunger\", needs.hunger, 10000)" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "ui.progress", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [ "label: visible metric label.", "value: current numeric value.", "maximum: positive upper bound." ], "related": [ "ui" ], "returns": "No gameplay value. The call appends or updates semantic presentation state for the current composition pass.", "signature": "ui.progress(label, value, maximum)", "usage": "Call during composition to append validated semantic presentation state. This function cannot mutate simulation owners." }, "errors": [], "fields": [], "id": "ui.progress", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "function", "name": "progress", "namespace": "ui", "owner": "app.ScriptPackageHost", "replacement": null, "side_effects": "records bounded detached presentation intent", "signature": "ui.progress(label, value, maximum)", "source_location": "src/app/script_package_host.cpp", "timing": "composition", "units": null, "url": "/api/v1/symbols/ui.progress.html" }, { "authority": "presentation", "availability": "Phase 14 package callbacks", "deprecated": null, "description": "Records one labeled value row.", "determinism": "Host-created package identity and per-callback budgets.", "documentation": { "cost": "Counts against the package composition instruction and surface work budgets; it does not traverse simulation ownership.", "examples": [ "ui.row(\"Villagers\", tostring(settlement.actor_count))" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "ui.row", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [ "label: visible row label.", "value: detached value rendered beside the label." ], "related": [ "ui" ], "returns": "No gameplay value. The call appends or updates semantic presentation state for the current composition pass.", "signature": "ui.row(label, value)", "usage": "Call during composition to append validated semantic presentation state. This function cannot mutate simulation owners." }, "errors": [], "fields": [], "id": "ui.row", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "function", "name": "row", "namespace": "ui", "owner": "app.ScriptPackageHost", "replacement": null, "side_effects": "records bounded detached presentation intent", "signature": "ui.row(label, value)", "source_location": "src/app/script_package_host.cpp", "timing": "composition", "units": null, "url": "/api/v1/symbols/ui.row.html" }, { "authority": "presentation", "availability": "Phase 14 package callbacks", "deprecated": null, "description": "Requests one declared provider for a replaceable UI surface.", "determinism": "Host-created package identity and per-callback budgets.", "documentation": { "cost": "Counts against the package composition instruction and surface work budgets; it does not traverse simulation ownership.", "examples": [ "ui.select_provider(\"ui.surface.player-hud\", \"worldforge.standard.player-hud\")" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "ui.select-provider", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [ "surface_id: registered replaceable surface.", "provider_id: registered provider for that surface." ], "related": [ "ui", "error.ui-composition-conflict", "ui.surface.player-hud" ], "returns": "No value. A valid selection changes the active provider at the host boundary.", "signature": "ui.select_provider(surface_id, provider_id)", "usage": "Select a registered provider for a replaceable surface. The compiled recovery surface is not selectable or replaceable." }, "errors": [ "error.ui-composition-conflict" ], "fields": [], "id": "ui.select-provider", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "function", "name": "select_provider", "namespace": "ui", "owner": "app.ScriptPackageHost", "replacement": null, "side_effects": "records bounded detached presentation intent", "signature": "ui.select_provider(surface_id, provider_id)", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/ui.select-provider.html" }, { "authority": "presentation", "availability": "Phase 14 package callbacks", "deprecated": null, "description": "Records a vertical group separator or horizontal panel separator.", "determinism": "Host-created package identity and per-callback budgets.", "documentation": { "cost": "Counts as one widget against the package composition budget.", "examples": [ "ui.begin_row_group()\nui.stat(\"10\", \"Residents\")\nui.separator()\nui.stat(\"4\", \"Households\")\nui.end_row_group()" ], "history": [ "1.19.0: Added orientation-aware panel separators." ], "id": "ui.separator", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.begin-row-group", "ui.widget.separator" ], "returns": "No gameplay value. The call appends one bounded structural presentation intent.", "signature": "ui.separator()", "usage": "Append a vertical separator inside a row group or a horizontal separator in normal panel flow." }, "errors": [], "fields": [], "id": "ui.separator", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "function", "name": "separator", "namespace": "ui", "owner": "app.ScriptPackageHost", "replacement": null, "side_effects": "records bounded detached presentation intent", "signature": "ui.separator()", "source_location": "src/app/script_package_host.cpp", "timing": "composition", "units": null, "url": "/api/v1/symbols/ui.separator.html" }, { "authority": "presentation", "availability": "Phase 14 package callbacks", "deprecated": null, "description": "Selects typed scale and accessibility theme constraints.", "determinism": "Host-created package identity and per-callback budgets.", "documentation": { "cost": "Counts against the package composition instruction and surface work budgets; it does not traverse simulation ownership.", "examples": [ "ui.set_theme({id = \"worldforge.standard\", text_scale = 1.0, high_contrast = false, reduced_motion = false})" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "ui.set-theme", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [ "theme_contract: table containing id, text_scale, high_contrast, and reduced_motion." ], "related": [ "ui", "error.invalid-theme", "ui.theme.color" ], "returns": "No gameplay value. The call appends or updates semantic presentation state for the current composition pass.", "signature": "ui.set_theme(theme_contract)", "usage": "Call during composition to append validated semantic presentation state. This function cannot mutate simulation owners." }, "errors": [ "error.invalid-theme" ], "fields": [], "id": "ui.set-theme", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "function", "name": "set_theme", "namespace": "ui", "owner": "app.ScriptPackageHost", "replacement": null, "side_effects": "records bounded detached presentation intent", "signature": "ui.set_theme(theme_contract)", "source_location": "src/app/script_package_host.cpp", "timing": "composition", "units": null, "url": "/api/v1/symbols/ui.set-theme.html" }, { "authority": "presentation", "availability": "runtime API 1", "deprecated": null, "description": "Versioned extension points inside registered surfaces.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Namespace lookup is constant-time and performs no owner work.", "examples": [ "-- Access documented members through ui.slot.player-hud.panels." ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "ui.slot", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.slot.player-hud.panels", "ui.slot.player-hud.toolbar", "ui.slot.recovery.status" ], "returns": "A stable namespace table containing only the documented child symbols available to this package origin.", "signature": "namespace ui.slot", "usage": "Use ui.slot only to reach its registered child contracts. The namespace itself performs no query, mutation, lifecycle transition, or drawing." }, "errors": [], "fields": [], "id": "ui.slot", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "namespace", "name": "Interface slots", "namespace": "ui.slot", "owner": "app.UiCompositionRegistry", "replacement": null, "side_effects": "none", "signature": "namespace ui.slot", "source_location": "src/app/script_api_catalog.cpp", "timing": "composition", "units": null, "url": "/api/v1/symbols/ui.slot.html" }, { "authority": "presentation", "availability": "active interface composition", "deprecated": null, "description": "Stable UI composition surface.", "determinism": "dependency order then stable package and contribution IDs", "documentation": { "cost": "Constant-size contract lookup or bounded retained-record access.", "examples": [ "-- Declare \"ui.slot.player-hud.panels\" in the package manifest UI contribution contract." ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "ui.slot.player-hud.panels", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.slot", "error.ui-composition-conflict" ], "returns": "A stable slot contract consumed by the interface composition host.", "signature": "slot(maximum=32)", "usage": "Target ui.slot.player-hud.panels from a manifest contribution whose semantic role and cardinality match the registered slot." }, "errors": [ "error.ui-composition-conflict" ], "fields": [], "id": "ui.slot.player-hud.panels", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "slot", "name": "panels", "namespace": "ui.slot", "owner": "app.UiCompositionRegistry", "replacement": null, "side_effects": "presentation only", "signature": "slot(maximum=32)", "source_location": "src/app/ui_composition_registry.cpp", "timing": "composition", "units": null, "url": "/api/v1/symbols/ui.slot.player-hud.panels.html" }, { "authority": "presentation", "availability": "active interface composition", "deprecated": null, "description": "Stable UI composition surface.", "determinism": "dependency order then stable package and contribution IDs", "documentation": { "cost": "Constant-size contract lookup or bounded retained-record access.", "examples": [ "-- Declare \"ui.slot.player-hud.toolbar\" in the package manifest UI contribution contract." ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "ui.slot.player-hud.toolbar", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.slot", "error.ui-composition-conflict" ], "returns": "A stable slot contract consumed by the interface composition host.", "signature": "slot(maximum=32)", "usage": "Target ui.slot.player-hud.toolbar from a manifest contribution whose semantic role and cardinality match the registered slot." }, "errors": [ "error.ui-composition-conflict" ], "fields": [], "id": "ui.slot.player-hud.toolbar", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "slot", "name": "toolbar", "namespace": "ui.slot", "owner": "app.UiCompositionRegistry", "replacement": null, "side_effects": "presentation only", "signature": "slot(maximum=32)", "source_location": "src/app/ui_composition_registry.cpp", "timing": "composition", "units": null, "url": "/api/v1/symbols/ui.slot.player-hud.toolbar.html" }, { "authority": "presentation", "availability": "active interface composition", "deprecated": null, "description": "Stable UI composition surface.", "determinism": "dependency order then stable package and contribution IDs", "documentation": { "cost": "Constant-size contract lookup or bounded retained-record access.", "examples": [ "-- Declare \"ui.slot.recovery.status\" in the package manifest UI contribution contract." ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "ui.slot.recovery.status", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.slot", "error.ui-composition-conflict" ], "returns": "A stable slot contract consumed by the interface composition host.", "signature": "slot(maximum=8)", "usage": "Target ui.slot.recovery.status from a manifest contribution whose semantic role and cardinality match the registered slot." }, "errors": [ "error.ui-composition-conflict" ], "fields": [], "id": "ui.slot.recovery.status", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "slot", "name": "status", "namespace": "ui.slot", "owner": "app.UiCompositionRegistry", "replacement": null, "side_effects": "presentation only", "signature": "slot(maximum=8)", "source_location": "src/app/ui_composition_registry.cpp", "timing": "composition", "units": null, "url": "/api/v1/symbols/ui.slot.recovery.status.html" }, { "authority": "presentation", "availability": "Phase 14 package callbacks", "deprecated": null, "description": "Consumes remaining width inside a horizontal widget group.", "determinism": "Host-created package identity and per-callback budgets.", "documentation": { "cost": "Counts as one widget against the package composition budget.", "examples": [ "ui.begin_row_group()\nui.text(\"Village\")\nui.spacer()\nui.text(\"Running\")\nui.end_row_group()" ], "history": [ "1.19.0: Added remaining-width row-group spacing." ], "id": "ui.spacer", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.begin-row-group", "ui.widget.spacer" ], "returns": "No gameplay value. The call appends one bounded structural presentation intent.", "signature": "ui.spacer()", "usage": "Consume the remaining horizontal width in the current row group so later widgets align to the far edge. Outside a row group the spacer has no visible effect." }, "errors": [], "fields": [], "id": "ui.spacer", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "function", "name": "spacer", "namespace": "ui", "owner": "app.ScriptPackageHost", "replacement": null, "side_effects": "records bounded detached presentation intent", "signature": "ui.spacer()", "source_location": "src/app/script_package_host.cpp", "timing": "composition", "units": null, "url": "/api/v1/symbols/ui.spacer.html" }, { "authority": "presentation", "availability": "Phase 14 package callbacks", "deprecated": null, "description": "Records one bounded spatial presentation surface.", "determinism": "Host-created package identity and per-callback budgets.", "documentation": { "cost": "One widget and its action identity against the composition budgets.", "examples": [ "ui.surface(\"minimap\", 1.6, \"ui.action.surface.minimap-select\")" ], "history": [ "1.19.0: Bounded spatial surfaces added for Phase 19Q9E." ], "id": "ui.spatial-surface", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [ "kind: minimap, region_map, or world_thumbnail.", "aspect: finite aspect ratio from 0.5 through 4.0.", "action_id: stable logical action for spatial activation." ], "related": [ "ui.widget.surface", "ui.surface.kind", "ui.action.surface.minimap-select" ], "returns": "No gameplay value. The call appends detached spatial widget intent.", "signature": "ui.surface(kind, aspect, action_id)", "usage": "Declare one bounded minimap, region map, or world thumbnail inside the open panel. Activation returns a stable comma-separated World-cell coordinate as row_id." }, "errors": [], "fields": [], "id": "ui.spatial-surface", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "function", "name": "surface", "namespace": "ui", "owner": "app.ScriptPackageHost", "replacement": null, "side_effects": "records bounded detached presentation intent", "signature": "ui.surface(kind, aspect, action_id)", "source_location": "src/app/script_package_host.cpp", "timing": "composition", "units": null, "url": "/api/v1/symbols/ui.spatial-surface.html" }, { "authority": "presentation", "availability": "Phase 14 package callbacks", "deprecated": null, "description": "Records one compact figure with a caption.", "determinism": "Host-created package identity and per-callback budgets.", "documentation": { "cost": "Counts as one widget against the package composition budget.", "examples": [ "ui.stat(tostring(settlement.actor_count), \"Residents\")" ], "history": [ "1.19.0: Added compact HUD statistics." ], "id": "ui.stat", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [ "value: visible figure text.", "label: short visible caption." ], "related": [ "ui.begin-row-group", "ui.widget.stat" ], "returns": "No gameplay value. The call appends one bounded semantic presentation intent.", "signature": "ui.stat(value, label)", "usage": "Append a compact persistent HUD figure with its caption beneath it. Use detached values captured through existing queries." }, "errors": [], "fields": [], "id": "ui.stat", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "function", "name": "stat", "namespace": "ui", "owner": "app.ScriptPackageHost", "replacement": null, "side_effects": "records bounded detached presentation intent", "signature": "ui.stat(value, label)", "source_location": "src/app/script_package_host.cpp", "timing": "composition", "units": null, "url": "/api/v1/symbols/ui.stat.html" }, { "authority": "presentation", "availability": "runtime API 1", "deprecated": null, "description": "Versioned replaceable and non-replaceable interface surfaces.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Namespace lookup is constant-time and performs no owner work.", "examples": [ "-- Access documented members through ui.surface.panel." ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "ui.surface", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.surface.panel", "ui.surface.player-hud", "ui.surface.recovery" ], "returns": "A stable namespace table containing only the documented child symbols available to this package origin.", "signature": "namespace ui.surface", "usage": "Use ui.surface only to reach its registered child contracts. The namespace itself performs no query, mutation, lifecycle transition, or drawing." }, "errors": [], "fields": [], "id": "ui.surface", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "namespace", "name": "Interface surfaces", "namespace": "ui.surface", "owner": "app.UiCompositionRegistry", "replacement": null, "side_effects": "none", "signature": "namespace ui.surface", "source_location": "src/app/script_api_catalog.cpp", "timing": "composition", "units": null, "url": "/api/v1/symbols/ui.surface.html" }, { "authority": "presentation", "availability": "Phase 19Q9E", "deprecated": null, "description": "Bounded spatial surface kind for overview and navigation presentation.", "determinism": "Exact registered identifiers only.", "documentation": { "cost": "Constant-size validation.", "examples": [ "ui.surface(\"region_map\", 1.8, \"ui.action.surface.region-select\")" ], "history": [ "1.19.0: Spatial surface kinds added for Phase 19Q9E." ], "id": "ui.surface.kind", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.spatial-surface", "ui.widget.surface" ], "returns": "A stable spatial-surface kind contract.", "signature": "minimap | region_map | world_thumbnail", "usage": "Choose the registered semantic kind for a bounded spatial surface. Exact identifiers keep package output portable across presentation backends." }, "errors": [], "fields": [], "id": "ui.surface.kind", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "type", "name": "kind", "namespace": "ui.surface", "owner": "app.ScriptUiWidget", "replacement": null, "side_effects": "Records detached presentation intent.", "signature": "minimap | region_map | world_thumbnail", "source_location": "src/app/script_ui_intent.hpp", "timing": "composition", "units": null, "url": "/api/v1/symbols/ui.surface.kind.html" }, { "authority": "presentation", "availability": "Phase 14G", "deprecated": null, "description": "Movable or fixed semantic panel with scale-aware anchored layout.", "determinism": "Stable package and emission order.", "documentation": { "cost": "Constant-size contract lookup or bounded retained-record access.", "examples": [ "-- Declare \"ui.surface.panel\" in the package manifest UI contribution contract." ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "ui.surface.panel", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.surface" ], "returns": "A stable surface contract consumed by the interface composition host.", "signature": "panel_contract", "usage": "Declare providers or contributions for ui.surface.panel in the package manifest. Replacement selection changes presentation ownership, never simulation ownership." }, "errors": [], "fields": [], "id": "ui.surface.panel", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "surface", "name": "panel", "namespace": "ui.surface", "owner": "app.ScriptUiIntentBuffer", "replacement": null, "side_effects": "Records detached presentation intent.", "signature": "panel_contract", "source_location": "src/app/script_ui_intent.hpp", "timing": "composition", "units": null, "url": "/api/v1/symbols/ui.surface.panel.html" }, { "authority": "presentation", "availability": "active interface composition", "deprecated": null, "description": "Stable UI composition surface.", "determinism": "dependency order then stable package and contribution IDs", "documentation": { "cost": "Constant-size contract lookup or bounded retained-record access.", "examples": [ "-- Declare \"ui.surface.player-hud\" in the package manifest UI contribution contract." ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "ui.surface.player-hud", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.surface", "error.ui-composition-conflict", "ui.slot.player-hud.panels", "ui.slot.player-hud.toolbar" ], "returns": "A stable surface contract consumed by the interface composition host.", "signature": "surface(context_version=1)", "usage": "Declare providers or contributions for ui.surface.player-hud in the package manifest. Replacement selection changes presentation ownership, never simulation ownership." }, "errors": [ "error.ui-composition-conflict" ], "fields": [], "id": "ui.surface.player-hud", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "surface", "name": "ui.surface.player-hud", "namespace": "ui.surface", "owner": "app.UiCompositionRegistry", "replacement": null, "side_effects": "presentation only", "signature": "surface(context_version=1)", "source_location": "src/app/ui_composition_registry.cpp", "timing": "composition", "units": null, "url": "/api/v1/symbols/ui.surface.player-hud.html" }, { "authority": "presentation", "availability": "active interface composition", "deprecated": null, "description": "Stable UI composition surface.", "determinism": "dependency order then stable package and contribution IDs", "documentation": { "cost": "Constant-size contract lookup or bounded retained-record access.", "examples": [ "-- Declare \"ui.surface.recovery\" in the package manifest UI contribution contract." ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "ui.surface.recovery", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.surface", "error.ui-composition-conflict", "ui.slot.recovery.status" ], "returns": "A stable surface contract consumed by the interface composition host.", "signature": "surface(context_version=1)", "usage": "Declare providers or contributions for ui.surface.recovery in the package manifest. Replacement selection changes presentation ownership, never simulation ownership." }, "errors": [ "error.ui-composition-conflict" ], "fields": [], "id": "ui.surface.recovery", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "surface", "name": "ui.surface.recovery", "namespace": "ui.surface", "owner": "app.UiCompositionRegistry", "replacement": null, "side_effects": "presentation only", "signature": "surface(context_version=1)", "source_location": "src/app/ui_composition_registry.cpp", "timing": "composition", "units": null, "url": "/api/v1/symbols/ui.surface.recovery.html" }, { "authority": "presentation", "availability": "Phase 14 package callbacks", "deprecated": null, "description": "Records one bounded tab strip before a panel's widgets.", "determinism": "Host-created package identity and per-callback budgets.", "documentation": { "cost": "Every tab counts against the widget budget and its label counts against the text budget.", "examples": [ "ui.tabs(\"ui.action.settlement.select-tab\", {\"Production\", \"Buildings\"}, 1)" ], "history": [ "1.19.0: Added bounded tab strips for Phase 19Q9D." ], "id": "ui.tabs", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [ "action_id: logical action dispatched on selection.", "labels: two through eight unique non-empty labels.", "active_index: one-based index of the active label." ], "related": [ "ui.widget.tabs", "ui.layout.sheet", "lifecycle.handle-action" ], "returns": "No gameplay value. The call appends detached tab presentation intent.", "signature": "ui.tabs(action_id, labels, active_index)", "usage": "Declare one bounded tab strip before the first widget in an open panel. Lua retains the active tab and receives the selected label as row_id." }, "errors": [], "fields": [], "id": "ui.tabs", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "function", "name": "tabs", "namespace": "ui", "owner": "app.ScriptPackageHost", "replacement": null, "side_effects": "records bounded detached presentation intent", "signature": "ui.tabs(action_id, labels, active_index)", "source_location": "src/app/script_package_host.cpp", "timing": "composition", "units": null, "url": "/api/v1/symbols/ui.tabs.html" }, { "authority": "presentation", "availability": "Phase 14 package callbacks", "deprecated": null, "description": "Records one text widget.", "determinism": "Host-created package identity and per-callback budgets.", "documentation": { "cost": "Counts against the package composition instruction and surface work budgets; it does not traverse simulation ownership.", "examples": [ "ui.text(\"Selection\", \"No villager selected\")" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "ui.text", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [ "label: visible text.", "value: optional value rendered beside the label." ], "related": [ "ui" ], "returns": "No gameplay value. The call appends or updates semantic presentation state for the current composition pass.", "signature": "ui.text(label, value?)", "usage": "Call during composition to append validated semantic presentation state. This function cannot mutate simulation owners." }, "errors": [], "fields": [], "id": "ui.text", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "function", "name": "text", "namespace": "ui", "owner": "app.ScriptPackageHost", "replacement": null, "side_effects": "records bounded detached presentation intent", "signature": "ui.text(label, value?)", "source_location": "src/app/script_package_host.cpp", "timing": "composition", "units": null, "url": "/api/v1/symbols/ui.text.html" }, { "authority": "presentation", "availability": "runtime API 1", "deprecated": null, "description": "Semantic colors with host-owned accessibility fallback.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Namespace lookup is constant-time and performs no owner work.", "examples": [ "-- Access documented members through ui.theme.color.accent." ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "ui.theme.color", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.theme.color.accent", "ui.theme.color.danger", "ui.theme.color.success", "ui.theme.color.text-muted", "ui.theme.color.text-primary", "ui.theme.color.warning" ], "returns": "A stable namespace table containing only the documented child symbols available to this package origin.", "signature": "namespace ui.theme.color", "usage": "Use ui.theme.color only to reach its registered child contracts. The namespace itself performs no query, mutation, lifecycle transition, or drawing." }, "errors": [], "fields": [], "id": "ui.theme.color", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "namespace", "name": "Theme colors", "namespace": "ui.theme.color", "owner": "app.ScriptUiTheme", "replacement": null, "side_effects": "none", "signature": "namespace ui.theme.color", "source_location": "src/app/script_api_catalog.cpp", "timing": "composition", "units": null, "url": "/api/v1/symbols/ui.theme.color.html" }, { "authority": "presentation", "availability": "Phase 14G", "deprecated": null, "description": "Typed semantic color token with host-owned accessibility fallback.", "determinism": "Theme token meaning is stable across renderer backends.", "documentation": { "cost": "Constant-size contract lookup or bounded retained-record access.", "examples": [ "-- Use ui.theme.color.accent through a validated ui.set_theme contract." ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "ui.theme.color.accent", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.theme.color", "ui.set-theme" ], "returns": "A stable theme token contract consumed by the interface composition host.", "signature": "ui.theme.color.accent", "usage": "Use ui.theme.color.accent through the validated theme contract. Packages request semantic styling and do not write renderer colors directly." }, "errors": [], "fields": [], "id": "ui.theme.color.accent", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "theme_token", "name": "accent", "namespace": "ui.theme.color", "owner": "app.ScriptUiTheme", "replacement": null, "side_effects": "none", "signature": "ui.theme.color.accent", "source_location": "src/app/script_ui_intent.hpp", "timing": "composition", "units": null, "url": "/api/v1/symbols/ui.theme.color.accent.html" }, { "authority": "presentation", "availability": "Phase 14G", "deprecated": null, "description": "Typed semantic color token with host-owned accessibility fallback.", "determinism": "Theme token meaning is stable across renderer backends.", "documentation": { "cost": "Constant-size contract lookup or bounded retained-record access.", "examples": [ "-- Use ui.theme.color.danger through a validated ui.set_theme contract." ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "ui.theme.color.danger", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.theme.color", "ui.set-theme" ], "returns": "A stable theme token contract consumed by the interface composition host.", "signature": "ui.theme.color.danger", "usage": "Use ui.theme.color.danger through the validated theme contract. Packages request semantic styling and do not write renderer colors directly." }, "errors": [], "fields": [], "id": "ui.theme.color.danger", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "theme_token", "name": "danger", "namespace": "ui.theme.color", "owner": "app.ScriptUiTheme", "replacement": null, "side_effects": "none", "signature": "ui.theme.color.danger", "source_location": "src/app/script_ui_intent.hpp", "timing": "composition", "units": null, "url": "/api/v1/symbols/ui.theme.color.danger.html" }, { "authority": "presentation", "availability": "Phase 14G", "deprecated": null, "description": "Typed semantic color token with host-owned accessibility fallback.", "determinism": "Theme token meaning is stable across renderer backends.", "documentation": { "cost": "Constant-size contract lookup or bounded retained-record access.", "examples": [ "-- Use ui.theme.color.success through a validated ui.set_theme contract." ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "ui.theme.color.success", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.theme.color", "ui.set-theme" ], "returns": "A stable theme token contract consumed by the interface composition host.", "signature": "ui.theme.color.success", "usage": "Use ui.theme.color.success through the validated theme contract. Packages request semantic styling and do not write renderer colors directly." }, "errors": [], "fields": [], "id": "ui.theme.color.success", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "theme_token", "name": "success", "namespace": "ui.theme.color", "owner": "app.ScriptUiTheme", "replacement": null, "side_effects": "none", "signature": "ui.theme.color.success", "source_location": "src/app/script_ui_intent.hpp", "timing": "composition", "units": null, "url": "/api/v1/symbols/ui.theme.color.success.html" }, { "authority": "presentation", "availability": "Phase 14G", "deprecated": null, "description": "Typed semantic color token with host-owned accessibility fallback.", "determinism": "Theme token meaning is stable across renderer backends.", "documentation": { "cost": "Constant-size contract lookup or bounded retained-record access.", "examples": [ "-- Use ui.theme.color.text-muted through a validated ui.set_theme contract." ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "ui.theme.color.text-muted", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.theme.color", "ui.set-theme" ], "returns": "A stable theme token contract consumed by the interface composition host.", "signature": "ui.theme.color.text-muted", "usage": "Use ui.theme.color.text-muted through the validated theme contract. Packages request semantic styling and do not write renderer colors directly." }, "errors": [], "fields": [], "id": "ui.theme.color.text-muted", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "theme_token", "name": "text-muted", "namespace": "ui.theme.color", "owner": "app.ScriptUiTheme", "replacement": null, "side_effects": "none", "signature": "ui.theme.color.text-muted", "source_location": "src/app/script_ui_intent.hpp", "timing": "composition", "units": null, "url": "/api/v1/symbols/ui.theme.color.text-muted.html" }, { "authority": "presentation", "availability": "Phase 14G", "deprecated": null, "description": "Typed semantic color token with host-owned accessibility fallback.", "determinism": "Theme token meaning is stable across renderer backends.", "documentation": { "cost": "Constant-size contract lookup or bounded retained-record access.", "examples": [ "-- Use ui.theme.color.text-primary through a validated ui.set_theme contract." ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "ui.theme.color.text-primary", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.theme.color", "ui.set-theme" ], "returns": "A stable theme token contract consumed by the interface composition host.", "signature": "ui.theme.color.text-primary", "usage": "Use ui.theme.color.text-primary through the validated theme contract. Packages request semantic styling and do not write renderer colors directly." }, "errors": [], "fields": [], "id": "ui.theme.color.text-primary", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "theme_token", "name": "text-primary", "namespace": "ui.theme.color", "owner": "app.ScriptUiTheme", "replacement": null, "side_effects": "none", "signature": "ui.theme.color.text-primary", "source_location": "src/app/script_ui_intent.hpp", "timing": "composition", "units": null, "url": "/api/v1/symbols/ui.theme.color.text-primary.html" }, { "authority": "presentation", "availability": "Phase 14G", "deprecated": null, "description": "Typed semantic color token with host-owned accessibility fallback.", "determinism": "Theme token meaning is stable across renderer backends.", "documentation": { "cost": "Constant-size contract lookup or bounded retained-record access.", "examples": [ "-- Use ui.theme.color.warning through a validated ui.set_theme contract." ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "ui.theme.color.warning", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.theme.color", "ui.set-theme" ], "returns": "A stable theme token contract consumed by the interface composition host.", "signature": "ui.theme.color.warning", "usage": "Use ui.theme.color.warning through the validated theme contract. Packages request semantic styling and do not write renderer colors directly." }, "errors": [], "fields": [], "id": "ui.theme.color.warning", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "theme_token", "name": "warning", "namespace": "ui.theme.color", "owner": "app.ScriptUiTheme", "replacement": null, "side_effects": "none", "signature": "ui.theme.color.warning", "source_location": "src/app/script_ui_intent.hpp", "timing": "composition", "units": null, "url": "/api/v1/symbols/ui.theme.color.warning.html" }, { "authority": "presentation", "availability": "Phase 14 package callbacks", "deprecated": null, "description": "Records tooltip content.", "determinism": "Host-created package identity and per-callback budgets.", "documentation": { "cost": "Counts against the package composition instruction and surface work budgets; it does not traverse simulation ownership.", "examples": [ "ui.tooltip(\"Need pressure\", \"Higher values require more attention.\")" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "ui.tooltip", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [ "label: semantic tooltip label.", "text: tooltip body." ], "related": [ "ui" ], "returns": "No gameplay value. The call appends or updates semantic presentation state for the current composition pass.", "signature": "ui.tooltip(label, text)", "usage": "Call during composition to append validated semantic presentation state. This function cannot mutate simulation owners." }, "errors": [], "fields": [], "id": "ui.tooltip", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "function", "name": "tooltip", "namespace": "ui", "owner": "app.ScriptPackageHost", "replacement": null, "side_effects": "records bounded detached presentation intent", "signature": "ui.tooltip(label, text)", "source_location": "src/app/script_package_host.cpp", "timing": "composition", "units": null, "url": "/api/v1/symbols/ui.tooltip.html" }, { "authority": "presentation", "availability": "runtime API 1", "deprecated": null, "description": "Backend-neutral semantic widgets recorded as detached intent.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Namespace lookup is constant-time and performs no owner work.", "examples": [ "-- Access documented members through ui.widget.button." ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "ui.widget", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.widget.button", "ui.widget.explain", "ui.widget.list", "ui.widget.list-row", "ui.widget.menu", "ui.widget.progress", "ui.widget.row", "ui.widget.row-group", "ui.widget.separator", "ui.widget.spacer", "ui.widget.stat", "ui.widget.text", "ui.widget.tooltip" ], "returns": "A stable namespace table containing only the documented child symbols available to this package origin.", "signature": "namespace ui.widget", "usage": "Use ui.widget only to reach its registered child contracts. The namespace itself performs no query, mutation, lifecycle transition, or drawing." }, "errors": [], "fields": [], "id": "ui.widget", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "namespace", "name": "Interface widgets", "namespace": "ui.widget", "owner": "app.ScriptUiWidget", "replacement": null, "side_effects": "none", "signature": "namespace ui.widget", "source_location": "src/app/script_api_catalog.cpp", "timing": "composition", "units": null, "url": "/api/v1/symbols/ui.widget.html" }, { "authority": "presentation", "availability": "Phase 14G", "deprecated": null, "description": "Keyboard-focusable logical-action button.", "determinism": "Action identity is independent of physical input.", "documentation": { "cost": "Counts against the package composition instruction and surface work budgets; it does not traverse simulation ownership.", "examples": [ "ui.button(\"Take Control\", \"ui.action.actor.take-control\", \"Directly control the selected villager\", 1)" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "ui.widget.button", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.widget", "ui.button" ], "returns": "A stable widget contract consumed by the interface composition host.", "signature": "ui.button(label, action_id, semantic_label, focus_order?)", "usage": "Compose this widget only inside a balanced ui.begin_panel and ui.end_panel block. Its semantic metadata and focus order remain part of the validated interface graph." }, "errors": [], "fields": [], "id": "ui.widget.button", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "widget", "name": "button", "namespace": "ui.widget", "owner": "app.ScriptUiWidget", "replacement": null, "side_effects": "Emits a Controls-owned logical action when activated.", "signature": "ui.button(label, action_id, semantic_label, focus_order?)", "source_location": "src/app/script_ui_intent.hpp", "timing": "composition", "units": null, "url": "/api/v1/symbols/ui.widget.button.html" }, { "authority": "presentation", "availability": "Phase 19Q9B", "deprecated": null, "description": "Full-width wrapped muted explanation paragraph.", "determinism": "Emission order.", "documentation": { "cost": "Counts against the bounded widget and text budgets.", "examples": [ "ui.explain(\"This villager is resting because fatigue is above the safe work threshold.\")" ], "history": [ "1.19.0: Added wrapped explanation presentation for Phase 19Q9B." ], "id": "ui.widget.explain", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.widget", "ui.explain" ], "returns": "A stable widget contract consumed by the interface composition host.", "signature": "ui.explain(text)", "usage": "Compose this full-width wrapped explanation inside a panel when the player needs the complete reason for a state, decision, or blocker." }, "errors": [], "fields": [], "id": "ui.widget.explain", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "widget", "name": "explain", "namespace": "ui.widget", "owner": "app.ScriptUiWidget", "replacement": null, "side_effects": "Records detached presentation intent.", "signature": "ui.explain(text)", "source_location": "src/app/script_ui_intent.hpp", "timing": "composition", "units": null, "url": "/api/v1/symbols/ui.widget.explain.html" }, { "authority": "presentation", "availability": "Phase 19Q9B", "deprecated": null, "description": "Scroll-bounded selectable rows with stable activation identities.", "determinism": "Emission order and stable row identity.", "documentation": { "cost": "The list and every contained row count against the bounded widget budget.", "examples": [ "ui.list(\"ui.action.alert.select\", alert_rows, {visible_rows = 4})" ], "history": [ "1.19.0: Added selectable list presentation for Phase 19Q9B." ], "id": "ui.widget.list", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.widget", "ui.widget.list-row", "ui.list", "lifecycle.handle-action" ], "returns": "A stable widget contract consumed by the interface composition host.", "signature": "ui.list(action_id, rows, options?)", "usage": "Compose a bounded selectable list inside a panel. Row activation preserves the selected stable identity instead of deriving behavior from visible text." }, "errors": [], "fields": [], "id": "ui.widget.list", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "widget", "name": "list", "namespace": "ui.widget", "owner": "app.ScriptUiWidget", "replacement": null, "side_effects": "Records detached presentation intent.", "signature": "ui.list(action_id, rows, options?)", "source_location": "src/app/script_ui_intent.hpp", "timing": "composition", "units": "rows", "url": "/api/v1/symbols/ui.widget.list.html" }, { "authority": "presentation", "availability": "Phase 19Q9B", "deprecated": null, "description": "One bounded list row with stable identity and optional progress.", "determinism": "Identity and declaration order.", "documentation": { "cost": "Counts as one widget plus its text against the composition budgets.", "examples": [ "{id = \"job:42\", label = \"Build east fence\", value = \"Blocked\", color = \"warning\", selected = true, progress = 0.4}" ], "history": [ "1.19.0: Added stable list row identities for Phase 19Q9B." ], "id": "ui.widget.list-row", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.widget", "ui.widget.list", "ui.list" ], "returns": "A stable row contract contained by ui.widget.list.", "signature": "{ id, label, value, color?, selected?, progress? }", "usage": "Give each list row a unique stable ID, visible label, optional detached value, semantic value color, selected state, and normalized progress from zero through one." }, "errors": [], "fields": [], "id": "ui.widget.list-row", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "type", "name": "list-row", "namespace": "ui.widget", "owner": "app.ScriptUiListRow", "replacement": null, "side_effects": "Records detached presentation intent.", "signature": "{ id, label, value, color?, selected?, progress? }", "source_location": "src/app/script_ui_intent.hpp", "timing": "composition", "units": null, "url": "/api/v1/symbols/ui.widget.list-row.html" }, { "authority": "presentation", "availability": "Phase 14G", "deprecated": null, "description": "Semantic menu heading.", "determinism": "Emission order.", "documentation": { "cost": "Counts against the package composition instruction and surface work budgets; it does not traverse simulation ownership.", "examples": [ "ui.menu(\"World\", \"Observe the settlement\")" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "ui.widget.menu", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.widget", "ui.menu" ], "returns": "A stable widget contract consumed by the interface composition host.", "signature": "ui.menu(label, state?)", "usage": "Compose this widget only inside a balanced ui.begin_panel and ui.end_panel block. Its semantic metadata and focus order remain part of the validated interface graph." }, "errors": [], "fields": [], "id": "ui.widget.menu", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "widget", "name": "menu", "namespace": "ui.widget", "owner": "app.ScriptUiWidget", "replacement": null, "side_effects": "Records detached presentation intent.", "signature": "ui.menu(label, state?)", "source_location": "src/app/script_ui_intent.hpp", "timing": "composition", "units": null, "url": "/api/v1/symbols/ui.widget.menu.html" }, { "authority": "presentation", "availability": "Phase 14G", "deprecated": null, "description": "Bounded progress with a non-color label.", "determinism": "Host clamps only at rendering.", "documentation": { "cost": "Counts against the package composition instruction and surface work budgets; it does not traverse simulation ownership.", "examples": [ "ui.progress(\"Hunger\", needs.hunger, 10000)" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "ui.widget.progress", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.widget", "ui.progress" ], "returns": "A stable widget contract consumed by the interface composition host.", "signature": "ui.progress(label, value, maximum)", "usage": "Compose this widget only inside a balanced ui.begin_panel and ui.end_panel block. Its semantic metadata and focus order remain part of the validated interface graph." }, "errors": [], "fields": [], "id": "ui.widget.progress", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "widget", "name": "progress", "namespace": "ui.widget", "owner": "app.ScriptUiWidget", "replacement": null, "side_effects": "Records detached presentation intent.", "signature": "ui.progress(label, value, maximum)", "source_location": "src/app/script_ui_intent.hpp", "timing": "composition", "units": null, "url": "/api/v1/symbols/ui.widget.progress.html" }, { "authority": "presentation", "availability": "Phase 14G", "deprecated": null, "description": "Labeled value row.", "determinism": "Emission order.", "documentation": { "cost": "Counts against the package composition instruction and surface work budgets; it does not traverse simulation ownership.", "examples": [ "ui.row(\"Villagers\", tostring(settlement.actor_count))" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "ui.widget.row", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.widget", "ui.row" ], "returns": "A stable widget contract consumed by the interface composition host.", "signature": "ui.row(label, value)", "usage": "Compose this widget only inside a balanced ui.begin_panel and ui.end_panel block. Its semantic metadata and focus order remain part of the validated interface graph." }, "errors": [], "fields": [], "id": "ui.widget.row", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "widget", "name": "row", "namespace": "ui.widget", "owner": "app.ScriptUiWidget", "replacement": null, "side_effects": "Records detached presentation intent.", "signature": "ui.row(label, value)", "source_location": "src/app/script_ui_intent.hpp", "timing": "composition", "units": null, "url": "/api/v1/symbols/ui.widget.row.html" }, { "authority": "presentation", "availability": "Phase 19Q9A", "deprecated": null, "description": "Non-nested horizontal widget group with bounded structural entries.", "determinism": "Emission order.", "documentation": { "cost": "Each group boundary counts against the bounded widget budget.", "examples": [ "ui.begin_row_group()\nui.text(\"Project\", \"Workshop\")\nui.end_row_group()" ], "history": [ "1.19.0: Added horizontal widget grouping." ], "id": "ui.widget.row-group", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.widget", "ui.begin-row-group", "ui.end-row-group" ], "returns": "A stable widget contract consumed by the interface composition host.", "signature": "ui.begin_row_group() ... ui.end_row_group()", "usage": "Compose this non-nested structural widget only inside a balanced ui.begin_panel and ui.end_panel block. Widgets between its boundaries render horizontally in emission order." }, "errors": [], "fields": [], "id": "ui.widget.row-group", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "widget", "name": "row-group", "namespace": "ui.widget", "owner": "app.ScriptUiWidget", "replacement": null, "side_effects": "Records detached presentation intent.", "signature": "ui.begin_row_group() ... ui.end_row_group()", "source_location": "src/app/script_ui_intent.hpp", "timing": "composition", "units": null, "url": "/api/v1/symbols/ui.widget.row-group.html" }, { "authority": "presentation", "availability": "Phase 19Q9A", "deprecated": null, "description": "Orientation-aware separator for panel or row-group layout.", "determinism": "Emission order.", "documentation": { "cost": "Counts against the bounded widget budget.", "examples": [ "ui.separator()" ], "history": [ "1.19.0: Added orientation-aware separators." ], "id": "ui.widget.separator", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.widget", "ui.separator" ], "returns": "A stable widget contract consumed by the interface composition host.", "signature": "ui.separator()", "usage": "Compose this structural widget inside a panel. Its orientation follows whether a row group is currently open." }, "errors": [], "fields": [], "id": "ui.widget.separator", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "widget", "name": "separator", "namespace": "ui.widget", "owner": "app.ScriptUiWidget", "replacement": null, "side_effects": "Records detached presentation intent.", "signature": "ui.separator()", "source_location": "src/app/script_ui_intent.hpp", "timing": "composition", "units": null, "url": "/api/v1/symbols/ui.widget.separator.html" }, { "authority": "presentation", "availability": "Phase 19Q9A", "deprecated": null, "description": "Remaining-width spacer for a horizontal group.", "determinism": "Emission order.", "documentation": { "cost": "Counts against the bounded widget budget.", "examples": [ "ui.spacer()" ], "history": [ "1.19.0: Added row-group spacing." ], "id": "ui.widget.spacer", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.widget", "ui.spacer" ], "returns": "A stable widget contract consumed by the interface composition host.", "signature": "ui.spacer()", "usage": "Compose this structural widget inside a row group to align later items to the far edge." }, "errors": [], "fields": [], "id": "ui.widget.spacer", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "widget", "name": "spacer", "namespace": "ui.widget", "owner": "app.ScriptUiWidget", "replacement": null, "side_effects": "Records detached presentation intent.", "signature": "ui.spacer()", "source_location": "src/app/script_ui_intent.hpp", "timing": "composition", "units": null, "url": "/api/v1/symbols/ui.widget.spacer.html" }, { "authority": "presentation", "availability": "Phase 19Q9A", "deprecated": null, "description": "Compact figure with a caption for persistent HUD summaries.", "determinism": "Emission order.", "documentation": { "cost": "Counts against the bounded widget budget.", "examples": [ "ui.stat(\"10\", \"Residents\")" ], "history": [ "1.19.0: Added compact HUD statistics." ], "id": "ui.widget.stat", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.widget", "ui.stat" ], "returns": "A stable widget contract consumed by the interface composition host.", "signature": "ui.stat(value, label)", "usage": "Compose this widget inside a panel to display one compact persistent figure and caption." }, "errors": [], "fields": [], "id": "ui.widget.stat", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "widget", "name": "stat", "namespace": "ui.widget", "owner": "app.ScriptUiWidget", "replacement": null, "side_effects": "Records detached presentation intent.", "signature": "ui.stat(value, label)", "source_location": "src/app/script_ui_intent.hpp", "timing": "composition", "units": null, "url": "/api/v1/symbols/ui.widget.stat.html" }, { "authority": "presentation", "availability": "Phase 19Q9E", "deprecated": null, "description": "Bounded spatial overview that emits a stable World-cell activation.", "determinism": "Click coordinates are normalized against Render camera bounds.", "documentation": { "cost": "One bounded draw surface and one activation target.", "examples": [ "ui.surface(\"minimap\", 1.6, \"ui.action.surface.minimap-select\")" ], "history": [ "1.19.0: Spatial surface widget added for Phase 19Q9E." ], "id": "ui.widget.surface", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.widget", "ui.spatial-surface", "ui.surface.kind" ], "returns": "A stable widget contract consumed by the interface renderer.", "signature": "ui.surface(kind, aspect, action_id)", "usage": "Render a bounded spatial overview in panel order and emit the selected World-cell coordinate through the declared logical action." }, "errors": [], "fields": [], "id": "ui.widget.surface", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "widget", "name": "surface", "namespace": "ui.widget", "owner": "app.ScriptUiWidget", "replacement": null, "side_effects": "Emits a Controls-owned logical action when activated.", "signature": "ui.surface(kind, aspect, action_id)", "source_location": "src/app/script_ui_intent.hpp", "timing": "composition", "units": "aspect ratio", "url": "/api/v1/symbols/ui.widget.surface.html" }, { "authority": "presentation", "availability": "Phase 19Q9D", "deprecated": null, "description": "Bounded tab labels with one active index and stable action identity.", "determinism": "Declaration order and active index.", "documentation": { "cost": "Two through eight bounded tab items plus their text.", "examples": [ "ui.tabs(\"ui.action.settlement.select-tab\", settlement_tabs, active_tab)" ], "history": [ "1.19.0: Added tab presentation for Phase 19Q9D." ], "id": "ui.widget.tabs", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.widget", "ui.tabs", "ui.layout.sheet" ], "returns": "A stable widget contract consumed by the interface composition host.", "signature": "ui.tabs(action_id, labels, active_index)", "usage": "Compose one keyboard-selectable tab strip at the start of a panel and preserve the selected stable label in the activation." }, "errors": [], "fields": [], "id": "ui.widget.tabs", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "widget", "name": "tabs", "namespace": "ui.widget", "owner": "app.ScriptUiTabStrip", "replacement": null, "side_effects": "Records detached presentation intent.", "signature": "ui.tabs(action_id, labels, active_index)", "source_location": "src/app/script_ui_intent.hpp", "timing": "composition", "units": "tabs", "url": "/api/v1/symbols/ui.widget.tabs.html" }, { "authority": "presentation", "availability": "Phase 14G", "deprecated": null, "description": "Semantic text.", "determinism": "Emission order.", "documentation": { "cost": "Counts against the package composition instruction and surface work budgets; it does not traverse simulation ownership.", "examples": [ "ui.text(\"Selection\", \"No villager selected\")" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "ui.widget.text", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.widget", "ui.text" ], "returns": "A stable widget contract consumed by the interface composition host.", "signature": "ui.text(label, value?)", "usage": "Compose this widget only inside a balanced ui.begin_panel and ui.end_panel block. Its semantic metadata and focus order remain part of the validated interface graph." }, "errors": [], "fields": [], "id": "ui.widget.text", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "widget", "name": "text", "namespace": "ui.widget", "owner": "app.ScriptUiWidget", "replacement": null, "side_effects": "Records detached presentation intent.", "signature": "ui.text(label, value?)", "source_location": "src/app/script_ui_intent.hpp", "timing": "composition", "units": null, "url": "/api/v1/symbols/ui.widget.text.html" }, { "authority": "presentation", "availability": "Phase 14G", "deprecated": null, "description": "Hover and focus help content.", "determinism": "Emission order.", "documentation": { "cost": "Counts against the package composition instruction and surface work budgets; it does not traverse simulation ownership.", "examples": [ "ui.tooltip(\"Need pressure\", \"Higher values require more attention.\")" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "ui.widget.tooltip", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "ui.widget", "ui.tooltip" ], "returns": "A stable widget contract consumed by the interface composition host.", "signature": "ui.tooltip(label, text)", "usage": "Compose this widget only inside a balanced ui.begin_panel and ui.end_panel block. Its semantic metadata and focus order remain part of the validated interface graph." }, "errors": [], "fields": [], "id": "ui.widget.tooltip", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "widget", "name": "tooltip", "namespace": "ui.widget", "owner": "app.ScriptUiWidget", "replacement": null, "side_effects": "Records detached presentation intent.", "signature": "ui.tooltip(label, text)", "source_location": "src/app/script_ui_intent.hpp", "timing": "composition", "units": null, "url": "/api/v1/symbols/ui.widget.tooltip.html" }, { "authority": "read_only", "availability": "runtime API 1", "deprecated": null, "description": "Entry point for registered detached world queries.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Namespace lookup is constant-time and performs no owner work.", "examples": [ "-- Access documented members through world.query." ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "world", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "world.query" ], "returns": "A stable namespace table containing only the documented child symbols available to this package origin.", "signature": "namespace world", "usage": "Use world only to reach its registered child contracts. The namespace itself performs no query, mutation, lifecycle transition, or drawing." }, "errors": [], "fields": [], "id": "world", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "namespace", "name": "World queries", "namespace": "world", "owner": "app.script-query-service", "replacement": null, "side_effects": "none", "signature": "namespace world", "source_location": "src/app/script_api_catalog.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.html" }, { "authority": "read_only", "availability": "runtime API 1", "deprecated": null, "description": "Detached current Actor facts.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Namespace lookup is constant-time and performs no owner work.", "examples": [ "-- Access documented members through world.actor.info." ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "world.actor", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "world.actor.info", "world.actor.needs", "world.actor.routine" ], "returns": "A stable namespace table containing only the documented child symbols available to this package origin.", "signature": "namespace world.actor", "usage": "Use world.actor only to reach its registered child contracts. The namespace itself performs no query, mutation, lifecycle transition, or drawing." }, "errors": [], "fields": [], "id": "world.actor", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "namespace", "name": "Actor queries", "namespace": "world.actor", "owner": "game.actor-runtime", "replacement": null, "side_effects": "none", "signature": "namespace world.actor", "source_location": "src/app/script_api_catalog.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.actor.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns paginated detached resource quantities carried by one actor.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "One Actor-container lookup and one bounded resource-definition visit per returned row.", "examples": [ "local cargo = world.query(\"world.actor.cargo\", {page_size = 16, filters = {actor_id = selected_id}})" ], "history": [ "1.3.0: Detached Actor cargo query added for Phase 16D." ], "id": "world.actor.cargo", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [ "filters.actor_id: required stable Actor identity.", "cursor: optional continuation cursor.", "page_size: bounded resource-row limit." ], "related": [ "world.actor.status", "world.resource.counts", "world.query" ], "returns": "Detached carried-resource rows in stable resource order. An empty completed page means the Actor carries nothing.", "signature": "world.actor.cargo(filters?, cursor?, page_size?) -> query-page", "usage": "Query one actor_id to inspect the resources currently held in that Actor's carried inventory." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Actor identity.", "id": "actor_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Actor-carried inventory container identity.", "id": "container_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Inventory owner revision.", "id": "container_revision", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Quantity carried.", "id": "quantity", "required": true, "units": "resource-units", "value_type": "unsigned-integer" }, { "description": "Resource identity.", "id": "resource_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Authored resource key.", "id": "resource_key", "required": true, "units": null, "value_type": "string" } ], "id": "world.actor.cargo", "introduced": { "display": "1.3.0", "major": 1, "minor": 3, "patch": 0 }, "kind": "query", "name": "Actor cargo", "namespace": "world.actor", "owner": "game.resource-economy", "replacement": null, "side_effects": "none", "signature": "world.actor.cargo(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.actor.cargo.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns detached identity, affiliation, actor revision, control authority, and condition facts for one actor.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "Bounded by page size, per-package query budget, and the owning snapshot builder; results are detached before Lua receives them.", "examples": [ "local result = world.query(\"world.actor.info\", {page_size = 16})\nif result.status == \"completed\" then\n for _, record in ipairs(result.records) do\n -- Render or inspect detached record fields here.\n end\nend" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry.", "1.19.2: Actor-owned inherited appearance facts added for Village Life O1.", "1.19.3: Current work, carried equipment, health severity, and local weather facts added for Village Life O3 presentation control." ], "id": "world.actor.info", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [ "filters: optional table of query-specific stable IDs and bounded selectors.", "cursor: optional opaque continuation cursor returned by the same query.", "page_size: optional positive record limit capped by the host." ], "related": [ "world.actor", "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation", "world.query" ], "returns": "A detached query page with status, records, continuation metadata, and a stable diagnostic when the request cannot complete.", "signature": "world.actor.info(filters?, cursor?, page_size?) -> query-page", "usage": "Read stable Actor identity, role, life, plan, and versioned appearance-generation facts. The record also reports current work, carried work-tool and hunting-spear custody, injury and illness severity, and local weather used by detached presentation. These are source-owner facts; they do not expose sprite or mutation authority. Consume records during the current callback and use the returned cursor for bounded continuation." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Actor identity.", "id": "actor_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Affiliation identity.", "id": "affiliation_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Stable Actor-owned appearance generation key.", "id": "appearance_generation_key", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Authored appearance generator policy.", "id": "appearance_policy_id", "required": true, "units": null, "value_type": "string" }, { "description": "Control-authority owner revision.", "id": "authority_revision", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Inherited body-shape trait index.", "id": "body_shape", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Whether Resource custody currently supplies a hunting spear.", "id": "carries_hunting_spear", "required": true, "units": null, "value_type": "boolean" }, { "description": "Whether Resource custody currently supplies a carried work tool.", "id": "carries_work_tool", "required": true, "units": null, "value_type": "boolean" }, { "description": "Current actor control mode.", "id": "control_mode", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Current World-grid X coordinate.", "id": "current_cell_x", "required": true, "units": "grid-cells", "value_type": "signed-integer" }, { "description": "Current World-grid Y coordinate.", "id": "current_cell_y", "required": true, "units": "grid-cells", "value_type": "signed-integer" }, { "description": "Current embodied World X coordinate.", "id": "current_x_meters", "required": true, "units": "meters", "value_type": "number" }, { "description": "Current embodied World Y coordinate.", "id": "current_y_meters", "required": true, "units": "meters", "value_type": "number" }, { "description": "Inherited face-shape trait index.", "id": "face_shape", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Inherited hair-color trait index.", "id": "hair_color", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Inherited hair-texture trait index.", "id": "hair_texture", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Current Actor-owned illness severity.", "id": "illness_severity", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Current Actor-owned injury severity.", "id": "injury_severity", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Age-derived life stage.", "id": "life_stage", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Whether the actor is alive.", "id": "living", "required": true, "units": null, "value_type": "boolean" }, { "description": "Current World-owned weather at the embodied Actor site.", "id": "local_weather", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Owner revision.", "id": "revision", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Inherited skin-tone trait index.", "id": "skin_tone", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Whether Actor currently supplies a work layer.", "id": "working", "required": true, "units": null, "value_type": "boolean" } ], "id": "world.actor.info", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "query", "name": "Actor information", "namespace": "world.actor", "owner": "game.actor-runtime and game.control-authority", "replacement": null, "side_effects": "none", "signature": "world.actor.info(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.actor.info.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Pages one Actor's retained current job alternatives and complete personal scoring evidence.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "One indexed Actor lookup and one bounded visit per retained alternative.", "examples": [ "local choices = world.query(\"world.actor.job-choices\", {page_size = 16, filters = {actor_id = selected_id}})\nif choices.status == \"completed\" then\n for _, choice in ipairs(choices.records) do\n if choice.selected then\n ui.text(\"Chosen work\", choice.source_kind)\n end\n end\nend" ], "history": [ "1.19.0: Actor-owned personal job alternatives and complete scoring evidence added for Phase 19Q4B2." ], "id": "world.actor.job-choices", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [ "filters.actor_id: required stable Actor identity.", "cursor: optional continuation cursor.", "page_size: bounded alternative-row limit." ], "related": [ "world.actor.status", "world.actor.routine", "world.job.info", "world.query" ], "returns": "Detached alternative rows with the choice revision, policy version, evaluation tick, outcome, selected job, Work source and demand identities, rejection, twelve scoring inputs, final score, and selected marker.", "signature": "world.actor.job-choices(filters?, cursor?, page_size?) -> query-page", "usage": "Query one actor_id to inspect the Actor-owned alternatives from the latest autonomous job evaluation. Read the selected alternative, hard rejections, and every personal and settlement scoring contribution without changing the choice." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Actor identity.", "id": "actor_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Actor capability fit.", "id": "capability_fit", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Actor-owned choice ledger revision.", "id": "choice_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Current commitment fit.", "id": "commitment_fit", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Actor condition readiness.", "id": "condition_readiness", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Route danger fit to personal tolerance.", "id": "danger_fit", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Alternative demand identity.", "id": "demand_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Choice evaluation tick.", "id": "evaluated_at_tick", "required": true, "units": "ticks", "value_type": "unsigned-integer" }, { "description": "Household obligation fit.", "id": "household_obligation", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Alternative job identity.", "id": "job_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Learned vocation preference.", "id": "learned_preference", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Overall job-choice outcome.", "id": "outcome", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Player-authored priority.", "id": "player_priority", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Recent-work variety fit.", "id": "recent_work_fit", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Hard rejection reason or none.", "id": "rejection", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Required resource readiness.", "id": "resource_readiness", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "World route cost.", "id": "route_cost", "required": true, "units": "ticks", "value_type": "unsigned-integer" }, { "description": "Current routine fit.", "id": "routine_fit", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Final authored-policy score.", "id": "score", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Whether this alternative was selected.", "id": "selected", "required": true, "units": null, "value_type": "boolean" }, { "description": "Selected job identity.", "id": "selected_job_id", "required": false, "units": null, "value_type": "stable-id-or-null" }, { "description": "Work source identity.", "id": "source_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Work source kind.", "id": "source_kind", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Authored scoring policy version.", "id": "tuning_version", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Settlement urgency contribution input.", "id": "urgency", "required": true, "units": "basis-points", "value_type": "unsigned-integer" } ], "id": "world.actor.job-choices", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "query", "name": "Actor job choices", "namespace": "world.actor", "owner": "game.actor-runtime", "replacement": null, "side_effects": "none", "signature": "world.actor.job-choices(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.actor.job-choices.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns the six current pressure values for one actor.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "Bounded by page size, per-package query budget, and the owning snapshot builder; results are detached before Lua receives them.", "examples": [ "local result = world.query(\"world.actor.needs\", {page_size = 16})\nif result.status == \"completed\" then\n for _, record in ipairs(result.records) do\n -- Render or inspect detached record fields here.\n end\nend" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry; Phase 16B added hydration pressure to the detached need fields." ], "id": "world.actor.needs", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [ "filters: optional table of query-specific stable IDs and bounded selectors.", "cursor: optional opaque continuation cursor returned by the same query.", "page_size: optional positive record limit capped by the host." ], "related": [ "world.actor", "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation", "world.query" ], "returns": "A detached query page with status, records, continuation metadata, and a stable diagnostic when the request cannot complete.", "signature": "world.actor.needs(filters?, cursor?, page_size?) -> query-page", "usage": "Call this query through world.query with the stable ID world.actor.needs. Each detached record includes hunger, hydration, rest, safety, warmth, and companionship pressure in basis points. Consume records during the current callback and use the returned cursor for bounded continuation." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Actor identity.", "id": "actor_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Companionship pressure.", "id": "companionship", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Hunger pressure.", "id": "hunger", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Hydration pressure.", "id": "hydration", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Rest pressure.", "id": "rest", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Safety pressure.", "id": "safety", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Warmth pressure.", "id": "warmth", "required": true, "units": "basis-points", "value_type": "unsigned-integer" } ], "id": "world.actor.needs", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "query", "name": "Actor needs", "namespace": "world.actor", "owner": "game.actor-runtime", "replacement": null, "side_effects": "none", "signature": "world.actor.needs(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.actor.needs.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns one Actor's retained social relationships in stable owner order.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "One Actor validation, one indexed Relationship lookup, and one bounded authored-name lookup per returned row.", "examples": [ "local relationships = world.query(\"world.actor.relationships\", {page_size = 4, filters = {actor_id = selected_id}})" ], "history": [ "1.10.0: Retained villager relationships exposed for Village Life addendum D." ], "id": "world.actor.relationships", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [ "filters.actor_id: required stable Actor identity.", "cursor: optional continuation cursor.", "page_size: bounded relationship-row limit." ], "related": [ "world.actor.status", "world.settlement.social-chronicle", "world.query" ], "returns": "Detached relationship rows in stable owner order with the other villager's authored display name.", "signature": "world.actor.relationships(filters?, cursor?, page_size?) -> query-page", "usage": "Query one actor_id to inspect the villager's retained social connections, current relationship stage, affinity, trust, strain, and latest change reason without changing either Actor." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Requested Actor identity.", "id": "actor_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Retained affinity.", "id": "affinity", "required": true, "units": "basis-points", "value_type": "signed-integer" }, { "description": "Reason for the latest relationship change.", "id": "last_reason", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Other Actor in the relationship.", "id": "peer_actor_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Authored peer name or stable fallback label.", "id": "peer_display_name", "required": true, "units": null, "value_type": "string" }, { "description": "Relationship identity.", "id": "relationship_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Current evaluated relationship stage.", "id": "stage", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Retained relationship strain.", "id": "strain", "required": true, "units": "basis-points", "value_type": "signed-integer" }, { "description": "Retained trust.", "id": "trust", "required": true, "units": "basis-points", "value_type": "signed-integer" }, { "description": "Latest relationship update.", "id": "updated_at_tick", "required": true, "units": "ticks", "value_type": "unsigned-integer" } ], "id": "world.actor.relationships", "introduced": { "display": "1.10.0", "major": 1, "minor": 10, "patch": 0 }, "kind": "query", "name": "Actor relationships", "namespace": "world.actor", "owner": "game.relationship and authored settlement", "replacement": null, "side_effects": "none", "signature": "world.actor.relationships(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.actor.relationships.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns one Actor's retained expected activity, actual choice, and reason.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "One indexed Actor lookup within the package query budget; no population scan or simulation mutation.", "examples": [ "local result = world.query(\"world.actor.routine\", {page_size = 1, filters = {actor_id = actor_id}})\nif result.status == \"completed\" then\n local routine = result.records[1]\n ui.row(\"Routine\", routine.actual_activity)\n ui.row(\"Expected\", routine.planned_activity)\nend" ], "history": [ "1.6.0: Detached resident routine and deviation evidence added for Phase 17A." ], "id": "world.actor.routine", "manual_nodes": [ "phase.17", "engine-reference.extension-contract" ], "parameters": [ "filters.actor_id: required stable Actor identity.", "cursor: optional continuation cursor; this single-record query normally returns none.", "page_size: positive record limit capped by the host." ], "related": [ "world.actor", "world.calendar.current", "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation", "world.query" ], "returns": "One detached routine record with the profile and routine revisions, expected and actual activities, decision reason, calendar position, completed day boundaries, deviation count, and whether the resident currently accepts new work.", "signature": "world.actor.routine(filters?, cursor?, page_size?) -> query-page", "usage": "Query one actor_id to read that resident's expected daily activity, current choice, and retained reason without requiring an embodied position. The result is detached and does not start, pause, or claim work." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Whether the current routine choice permits a new autonomous work claim.", "id": "accepts_new_work", "required": true, "units": null, "value_type": "boolean" }, { "description": "Actor identity.", "id": "actor_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Activity currently chosen by the Actor.", "id": "actual_activity", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Day evaluated by the Actor.", "id": "calendar_day", "required": true, "units": "days", "value_type": "unsigned-integer" }, { "description": "Day boundaries crossed through hot or compressed visits.", "id": "completed_day_boundaries", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Retained count of off-schedule choices.", "id": "deviations", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Last bounded routine visit.", "id": "evaluated_at_tick", "required": true, "units": "ticks", "value_type": "unsigned-integer" }, { "description": "Clock minute evaluated by the Actor.", "id": "minute_of_day", "required": true, "units": "minutes", "value_type": "unsigned-integer" }, { "description": "Activity expected by the daily schedule.", "id": "planned_activity", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Routine profile generator version.", "id": "profile_version", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Reason for the current choice.", "id": "reason", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Actor-owned routine revision.", "id": "routine_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Actor's stable personal timing offset from the authored routine.", "id": "schedule_offset_minutes", "required": true, "units": "minutes", "value_type": "signed-integer" } ], "id": "world.actor.routine", "introduced": { "display": "1.6.0", "major": 1, "minor": 6, "patch": 0 }, "kind": "query", "name": "Actor routine", "namespace": "world.actor", "owner": "game.actor-runtime", "replacement": null, "side_effects": "none", "signature": "world.actor.routine(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.actor.routine.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns detached authored identity, health, plan, task, work stage, progress, and destination facts for one actor.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "One Actor visit and bounded visits to the matching Supply or Construction owner.", "examples": [ "local result = world.query(\"world.actor.status\", {page_size = 1, filters = {actor_id = selected_id}})" ], "history": [ "1.3.0: Detached villager work status added for Phase 16D.", "1.8.0: Injury, illness, impairment, and recovery readiness added for Phase 17B.", "1.9.0: Authored profession identity and display name added for the village interface." ], "id": "world.actor.status", "manual_nodes": [ "phase.16", "phase.17", "engine-reference.extension-contract" ], "parameters": [ "filters.actor_id: required stable Actor identity.", "cursor: optional continuation cursor.", "page_size: bounded record limit." ], "related": [ "world.actor.info", "world.actor.needs", "world.actor.cargo", "world.household.for-actor" ], "returns": "One detached worker-status record, or a stable unavailable result when the Actor is not embodied or loaded.", "signature": "world.actor.status(filters?, cursor?, page_size?) -> query-page", "usage": "Query one actor_id to inspect the villager's authored name and profession, injury, illness, impairment, recovery readiness, current plan and task, work stage and progress, and current source or destination without changing behavior." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Actor identity.", "id": "actor_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Current plan or work destination site.", "id": "destination_site_id", "required": false, "units": null, "value_type": "stable-id-or-null" }, { "description": "Authored display name or stable fallback label.", "id": "display_name", "required": true, "units": null, "value_type": "string" }, { "description": "Current illness severity.", "id": "illness", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Current physical impairment.", "id": "impairment", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Current injury severity.", "id": "injury", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Current job identity.", "id": "job_id", "required": false, "units": null, "value_type": "stable-id-or-null" }, { "description": "Reason for the latest plan change.", "id": "plan_change", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Current plan kind.", "id": "plan_kind", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Current plan revision.", "id": "plan_revision", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Current plan status.", "id": "plan_status", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Authored profession identity when the scenario supplies one.", "id": "profession_definition_id", "required": false, "units": null, "value_type": "string-or-null" }, { "description": "Player-facing authored profession name.", "id": "profession_display_name", "required": false, "units": null, "value_type": "string-or-null" }, { "description": "Whether retained injury recovery is ready.", "id": "recovery_ready", "required": true, "units": null, "value_type": "boolean" }, { "description": "Current work source site.", "id": "source_site_id", "required": false, "units": null, "value_type": "stable-id-or-null" }, { "description": "Exact local destination X coordinate.", "id": "target_x_meters", "required": false, "units": "meters", "value_type": "number-or-null" }, { "description": "Exact local destination Y coordinate.", "id": "target_y_meters", "required": false, "units": "meters", "value_type": "number-or-null" }, { "description": "Current task kind.", "id": "task_kind", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Current task progress.", "id": "task_progress", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Current task status.", "id": "task_status", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Current supply, construction, or no work.", "id": "work_kind", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Current domain work progress.", "id": "work_progress", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Current domain-owned work stage.", "id": "work_stage", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Current work-task identity.", "id": "work_task_id", "required": false, "units": null, "value_type": "stable-id-or-null" } ], "id": "world.actor.status", "introduced": { "display": "1.3.0", "major": 1, "minor": 3, "patch": 0 }, "kind": "query", "name": "Actor work status", "namespace": "world.actor", "owner": "game.actor-runtime, game.settlement-supply, game.construction, and authored settlement", "replacement": null, "side_effects": "none", "signature": "world.actor.status(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.actor.status.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns paginated detached personal currency balances for one actor.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "One Actor-wallet lookup plus bounded content-catalog and Resource-definition visits.", "examples": [ "local money = world.query(\"world.actor.wealth\", {page_size = 8, filters = {actor_id = actor_id}})" ], "history": [ "1.4.0: Physical Actor wallet custody exposed for Phase 16D2." ], "id": "world.actor.wealth", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [ "filters.actor_id: required stable Actor identity.", "cursor: optional continuation cursor.", "page_size: bounded currency-row limit." ], "related": [ "world.household.wealth", "command.money.contribute", "world.query" ], "returns": "One detached row per authored currency in stable catalog order, including zero balances.", "signature": "world.actor.wealth(filters?, cursor?, page_size?) -> query-page", "usage": "Query one actor_id to read detached personal currency balances and the current wallet revision. The returned table cannot move or reserve money." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Actor identity.", "id": "actor_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Current personal balance.", "id": "balance", "required": true, "units": "minor-currency-units", "value_type": "unsigned-integer" }, { "description": "Actor-wallet container identity.", "id": "container_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Wallet owner revision.", "id": "container_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Authored currency definition identity.", "id": "currency_definition_id", "required": true, "units": null, "value_type": "string" }, { "description": "Player-facing currency name.", "id": "display_name", "required": true, "units": null, "value_type": "string" }, { "description": "Runtime Resource identity.", "id": "resource_id", "required": true, "units": null, "value_type": "stable-id" } ], "id": "world.actor.wealth", "introduced": { "display": "1.4.0", "major": 1, "minor": 4, "patch": 0 }, "kind": "query", "name": "Actor wealth", "namespace": "world.actor", "owner": "game.resource-economy and assets.runtime-content-catalog", "replacement": null, "side_effects": "none", "signature": "world.actor.wealth(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.actor.wealth.html" }, { "authority": "read_only", "availability": "runtime API 1", "deprecated": null, "description": "Detached current Construction-owned building facts.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Namespace lookup is constant-time and performs no owner work.", "examples": [ "-- Access documented members through world.building.info." ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "world.building", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "world.building.info" ], "returns": "A stable namespace table containing only the documented child symbols available to this package origin.", "signature": "namespace world.building", "usage": "Use world.building only to reach its registered child contracts. The namespace itself performs no query, mutation, lifecycle transition, or drawing." }, "errors": [], "fields": [], "id": "world.building", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "namespace", "name": "Building queries", "namespace": "world.building", "owner": "game.construction", "replacement": null, "side_effects": "none", "signature": "namespace world.building", "source_location": "src/app/script_api_catalog.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.building.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns one detached building record selected by stable building identity.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "One Building lookup and one bounded content-catalog lookup within the package query budget.", "examples": [ "local result = world.query(\"world.building.info\", {page_size = 1, filters = {building_id = building_id}})\nif result.status == \"completed\" then\n local building = result.records[1]\n ui.text(\"Building\", building.display_name)\n ui.row(\"Purpose\", building.function_label)\n ui.row(\"Condition\", tostring(building.condition_percent) .. \"% - \" .. building.condition_status)\nend" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry.", "1.5.0: Added the authored display_name field for normal interface labels.", "1.5.0: Added readable function and condition fields for the standard interface." ], "id": "world.building.info", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [ "filters.building_id: required stable Building identity.", "cursor: optional continuation cursor; this single-record query normally returns none.", "page_size: positive record limit capped by the host." ], "related": [ "world.building", "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation", "world.query" ], "returns": "One detached building record. display_name comes from the active content catalog and falls back to definition_id only when authored metadata is unavailable. function remains the stable machine identifier; function_label, condition_percent, and condition_status are intended for normal interface text.", "signature": "world.building.info(filters?, cursor?, page_size?) -> query-page", "usage": "Query one building_id to read its authored player-facing name, raw and readable function, lifecycle, basis-point and percentage condition, condition status, and revision without changing Construction or Building state." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Building identity.", "id": "building_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Current condition.", "id": "condition", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Rounded player-facing condition.", "id": "condition_percent", "required": true, "units": "percent", "value_type": "unsigned-integer" }, { "description": "Player-facing condition classification.", "id": "condition_status", "required": true, "units": null, "value_type": "string" }, { "description": "Authored building definition identity.", "id": "definition_id", "required": true, "units": null, "value_type": "string" }, { "description": "Player-facing authored building name.", "id": "display_name", "required": true, "units": null, "value_type": "string" }, { "description": "Building function.", "id": "function", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Player-facing building function label.", "id": "function_label", "required": true, "units": null, "value_type": "string" }, { "description": "Building lifecycle.", "id": "lifecycle", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Owner revision.", "id": "revision", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Current upgrade level.", "id": "upgrade_level", "required": true, "units": null, "value_type": "unsigned-integer" } ], "id": "world.building.info", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "query", "name": "Building information", "namespace": "world.building", "owner": "game.construction", "replacement": null, "side_effects": "none", "signature": "world.building.info(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.building.info.html" }, { "authority": "read_only", "availability": "runtime API 1", "deprecated": null, "description": "Detached current calendar and clock facts.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Namespace lookup is constant-time and performs no owner work.", "examples": [ "-- Access the current derived clock through world.calendar.current." ], "history": [ "1.6.0: Calendar query namespace added for Phase 17A." ], "id": "world.calendar", "manual_nodes": [ "phase.17", "engine-reference.extension-contract" ], "parameters": [], "related": [ "world.calendar.current" ], "returns": "A stable namespace table containing the documented calendar query available to this package origin.", "signature": "namespace world.calendar", "usage": "Use world.calendar to reach detached calendar facts derived from the authoritative World environment. The namespace itself performs no query, mutation, lifecycle transition, or drawing." }, "errors": [], "fields": [], "id": "world.calendar", "introduced": { "display": "1.6.0", "major": 1, "minor": 6, "patch": 0 }, "kind": "namespace", "name": "Calendar queries", "namespace": "world.calendar", "owner": "sim.world-environment", "replacement": null, "side_effects": "none", "signature": "namespace world.calendar", "source_location": "src/app/script_api_catalog.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.calendar.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns the current detached calendar day, clock, season, and day kind.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "Constant-time calendar derivation within the package query budget; no population or environment scan.", "examples": [ "local result = world.query(\"world.calendar.current\", {page_size = 1})\nif result.status == \"completed\" then\n local calendar = result.records[1]\n ui.row(\"World time\", \"Day \" .. tostring(calendar.absolute_day + 1) .. \" \" .. tostring(calendar.hour) .. \":\" .. tostring(calendar.minute))\nend" ], "history": [ "1.6.0: Derived World clock and day-kind query added for Phase 17A." ], "id": "world.calendar.current", "manual_nodes": [ "phase.17", "engine-reference.extension-contract" ], "parameters": [ "filters: no filters are required.", "cursor: optional continuation cursor; this single-record query normally returns none.", "page_size: positive record limit capped by the host." ], "related": [ "world.calendar", "world.actor.routine", "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation", "world.query" ], "returns": "One detached calendar record containing fixed tick, absolute day, year, day positions, weekday, hour, minute, day kind, season, and schedule window.", "signature": "world.calendar.current(filters?, cursor?, page_size?) -> query-page", "usage": "Read the current World day, season, clock, day kind, and schedule window. Every field is derived from the authoritative fixed tick and calendar policy; the query cannot change time." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Days elapsed since the world epoch.", "id": "absolute_day", "required": true, "units": "days", "value_type": "unsigned-integer" }, { "description": "Ordinary, rest-day, or festival schedule.", "id": "day_kind", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Zero-based day within the current season.", "id": "day_of_season", "required": true, "units": "days", "value_type": "unsigned-integer" }, { "description": "Zero-based weekday.", "id": "day_of_week", "required": true, "units": "days", "value_type": "unsigned-integer" }, { "description": "Zero-based day within the current year.", "id": "day_of_year", "required": true, "units": "days", "value_type": "unsigned-integer" }, { "description": "Hour of day.", "id": "hour", "required": true, "units": "hours", "value_type": "unsigned-integer" }, { "description": "Minute within the current hour.", "id": "minute", "required": true, "units": "minutes", "value_type": "unsigned-integer" }, { "description": "Current season.", "id": "season", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Current fixed simulation tick.", "id": "tick", "required": true, "units": "ticks", "value_type": "unsigned-integer" }, { "description": "Authored fixed ticks per day.", "id": "ticks_per_day", "required": true, "units": "ticks", "value_type": "unsigned-integer" }, { "description": "Current broad time window.", "id": "window", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Zero-based world year.", "id": "year", "required": true, "units": "years", "value_type": "unsigned-integer" } ], "id": "world.calendar.current", "introduced": { "display": "1.6.0", "major": 1, "minor": 6, "patch": 0 }, "kind": "query", "name": "World calendar", "namespace": "world.calendar", "owner": "sim.world-environment", "replacement": null, "side_effects": "none", "signature": "world.calendar.current(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.calendar.current.html" }, { "authority": "read_only", "availability": "runtime API 1", "deprecated": null, "description": "Detached current construction progress and blockage facts.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Namespace lookup is constant-time and performs no owner work.", "examples": [ "-- Access documented members through world.construction.progress." ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "world.construction", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "world.construction.progress" ], "returns": "A stable namespace table containing only the documented child symbols available to this package origin.", "signature": "namespace world.construction", "usage": "Use world.construction only to reach its registered child contracts. The namespace itself performs no query, mutation, lifecycle transition, or drawing." }, "errors": [], "fields": [], "id": "world.construction", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "namespace", "name": "Construction queries", "namespace": "world.construction", "owner": "game.construction", "replacement": null, "side_effects": "none", "signature": "namespace world.construction", "source_location": "src/app/script_api_catalog.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.construction.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns a bounded stable-ID window of current construction projects.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "Bounded active Construction index visits.", "examples": [ "local active = world.query(\"world.construction.active\", {page_size = 16})" ], "history": [ "1.5.0: Active construction query added for Phase 16D.", "1.5.0: Added worker-interruption recovery timing, successful handoff history, and failure cause for Phase 16F.", "1.9.0: Current Work player priority added for the normal village focus." ], "id": "world.construction.active", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [ "cursor: optional continuation cursor.", "page_size: bounded active-project count." ], "related": [ "world.construction", "command.construction.cancel", "world.construction.progress" ], "returns": "Active Construction identities, definitions, Work revisions and player priority, stages, blockage, interruption timing, successful handoff history, and failure cause in stable order.", "signature": "world.construction.active(filters?, cursor?, page_size?) -> query-page", "usage": "Read current active construction records, including worker-interruption blockage, recovery timing, and successful handoff history, before presenting status or submitting cancellation. Returned records are detached and cannot change the project." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Current blockage reason.", "id": "blockage", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Tick when the current blockage began.", "id": "blocked_since_tick", "required": false, "units": "fixed-ticks", "value_type": "unsigned-integer-or-null" }, { "description": "Construction identity.", "id": "construction_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Authored building definition identity.", "id": "definition_id", "required": true, "units": null, "value_type": "string" }, { "description": "Retained terminal failure cause.", "id": "failure_cause", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Construction Work job identity.", "id": "job_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Current Work job revision.", "id": "job_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Most recent retained worker-interruption tick.", "id": "last_worker_interruption_tick", "required": false, "units": "fixed-ticks", "value_type": "unsigned-integer-or-null" }, { "description": "Most recent successful worker-handoff tick.", "id": "last_worker_reassignment_tick", "required": false, "units": "fixed-ticks", "value_type": "unsigned-integer-or-null" }, { "description": "Construction origin X coordinate.", "id": "origin_x", "required": true, "units": "grid-cells", "value_type": "signed-integer" }, { "description": "Construction origin Y coordinate.", "id": "origin_y", "required": true, "units": "grid-cells", "value_type": "signed-integer" }, { "description": "Durable player-priority contribution.", "id": "player_priority", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Current construction revision.", "id": "revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Current construction stage.", "id": "stage", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Successful worker handoffs retained by Construction.", "id": "worker_handoff_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Tick when the worker-interruption recovery window expires.", "id": "worker_interruption_deadline_tick", "required": false, "units": "fixed-ticks", "value_type": "unsigned-integer-or-null" }, { "description": "Recovery ticks remaining before worker-interruption failure.", "id": "worker_interruption_grace_ticks_remaining", "required": false, "units": "fixed-ticks", "value_type": "unsigned-integer-or-null" } ], "id": "world.construction.active", "introduced": { "display": "1.5.0", "major": 1, "minor": 5, "patch": 0 }, "kind": "query", "name": "Active construction", "namespace": "world.construction", "owner": "game.construction", "replacement": null, "side_effects": "none", "signature": "world.construction.active(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.construction.active.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Validates one authored building footprint against the World grid and retained Construction occupancy without mutating either owner.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "One content lookup plus one bounded visit per footprint cell.", "examples": [ "local preview = world.query(\"world.construction.placement-preview\", {page_size = 1, filters = {definition_id = project.definition_id, origin_x = x, origin_y = y, orientation = orientation}})" ], "history": [ "1.19.0: Read-only construction placement validation added for Phase 19Q9E." ], "id": "world.construction.placement-preview", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [ "filters.definition_id: required authored building identity.", "filters.origin_x and filters.origin_y: required signed World-cell origin.", "filters.orientation: required integer from zero through three.", "cursor: must be zero.", "page_size: bounded record limit." ], "related": [ "world.project.alternatives", "ui.ghost", "command.construction.designate" ], "returns": "One detached record containing validity, detail, requested origin, oriented footprint origin and dimensions, orientation, and occupied cell count.", "signature": "world.construction.placement-preview(filters?, cursor?, page_size?) -> query-page", "usage": "Validate one authored building footprint against the current World grid and Construction occupancy without mutating either owner. Use the returned oriented bounds for ui.ghost and require valid before offering designation." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Specific validation result.", "id": "detail", "required": true, "units": null, "value_type": "string" }, { "description": "Validated occupied cell count.", "id": "footprint_cells", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Oriented bounding footprint height.", "id": "footprint_height_cells", "required": true, "units": "World-grid cells", "value_type": "unsigned-integer" }, { "description": "Minimum occupied X coordinate.", "id": "footprint_origin_x", "required": true, "units": "World-grid cells", "value_type": "signed-integer" }, { "description": "Minimum occupied Y coordinate.", "id": "footprint_origin_y", "required": true, "units": "World-grid cells", "value_type": "signed-integer" }, { "description": "Oriented bounding footprint width.", "id": "footprint_width_cells", "required": true, "units": "World-grid cells", "value_type": "unsigned-integer" }, { "description": "Requested construction orientation.", "id": "orientation", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Requested footprint origin.", "id": "origin_x", "required": true, "units": "World-grid cells", "value_type": "signed-integer" }, { "description": "Requested footprint origin.", "id": "origin_y", "required": true, "units": "World-grid cells", "value_type": "signed-integer" }, { "description": "Whether designation can occupy the requested cells.", "id": "valid", "required": true, "units": null, "value_type": "boolean" } ], "id": "world.construction.placement-preview", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "query", "name": "Construction placement preview", "namespace": "world.construction", "owner": "game.construction and sim.world-grid", "replacement": null, "side_effects": "none", "signature": "world.construction.placement-preview(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.construction.placement-preview.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns detached physical work, assigned-Actor throughput, duration, and blockage facts for one construction project.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "One Construction lookup and, when a worker is assigned, one Actor lookup within package query budgets.", "examples": [ "local result = world.query(\"world.construction.progress\", {page_size = 1, filters = {construction_id = 1}})\nif result.status == \"completed\" then\n local project = result.records[1]\n ui.row(\"Build work\", tostring(project.completed_work_units) .. \" / \" .. tostring(project.required_work_units))\n if project.blockage == \"worker_interrupted\" then\n ui.row(\"Recovery window\", tostring(project.worker_interruption_grace_ticks_remaining) .. \" ticks\")\n elseif project.failure_cause ~= \"none\" then\n ui.text(\"Construction failed\", project.failure_cause)\n end\nend" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry.", "1.1.0: Replaced tick-named progress with physical work units, fractional remainder, Actor rate, and duration fields.", "1.5.0: Added worker-interruption timing, successful handoff history, and retained failure cause for Phase 16F." ], "id": "world.construction.progress", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [ "filters.construction_id: required stable construction identity.", "cursor: optional continuation cursor; this single-record query normally returns none.", "page_size: positive record limit capped by the host." ], "related": [ "world.construction", "developer.tuning.values", "restricted.tuning.set-value", "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation", "world.query" ], "returns": "One detached construction record. Worker and rate-derived fields are null when no Actor is assigned. Interruption timing fields are null unless the project is blocked by a worker interruption.", "signature": "world.construction.progress(filters?, cursor?, page_size?) -> query-page", "usage": "Query one construction identity to inspect authored work, deterministic fractional progress, the assigned Actor's rate modifier, effective throughput, estimated remaining fixed ticks, stage, blockage, worker-interruption recovery deadline, retained handoff history, and terminal failure cause. Values are detached and cannot mutate Construction or Actor owners." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Current runtime base construction throughput.", "id": "base_work_units_per_second", "required": true, "units": "work-units-per-second", "value_type": "unsigned-integer" }, { "description": "Current blockage reason.", "id": "blockage", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Tick when the current blockage began.", "id": "blocked_since_tick", "required": false, "units": "fixed-ticks", "value_type": "unsigned-integer-or-null" }, { "description": "Completed physical work.", "id": "completed_work_units", "required": true, "units": "work-units", "value_type": "unsigned-integer" }, { "description": "Construction identity.", "id": "construction_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Authored building definition identity.", "id": "definition_id", "required": true, "units": null, "value_type": "string" }, { "description": "Derived base throughput after the assigned Actor modifier.", "id": "effective_work_units_per_second", "required": false, "units": "work-units-per-second", "value_type": "number-or-null" }, { "description": "Derived fixed ticks remaining at the current rate.", "id": "estimated_remaining_ticks", "required": false, "units": "fixed-ticks", "value_type": "unsigned-integer-or-null" }, { "description": "Retained terminal failure cause.", "id": "failure_cause", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Most recent retained worker-interruption tick.", "id": "last_worker_interruption_tick", "required": false, "units": "fixed-ticks", "value_type": "unsigned-integer-or-null" }, { "description": "Most recent successful worker-handoff tick.", "id": "last_worker_reassignment_tick", "required": false, "units": "fixed-ticks", "value_type": "unsigned-integer-or-null" }, { "description": "Derived completion ratio.", "id": "progress", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Authored physical work required.", "id": "required_work_units", "required": true, "units": "work-units", "value_type": "unsigned-integer" }, { "description": "Current construction stage.", "id": "stage", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Retained deterministic fractional work numerator.", "id": "work_remainder_numerator", "required": true, "units": "construction-work-rate-numerator", "value_type": "unsigned-integer" }, { "description": "Assigned construction Actor when present.", "id": "worker_actor_id", "required": false, "units": null, "value_type": "stable-id-or-null" }, { "description": "Successful worker handoffs retained by Construction.", "id": "worker_handoff_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Tick when the worker-interruption recovery window expires.", "id": "worker_interruption_deadline_tick", "required": false, "units": "fixed-ticks", "value_type": "unsigned-integer-or-null" }, { "description": "Recovery ticks remaining before worker-interruption failure.", "id": "worker_interruption_grace_ticks_remaining", "required": false, "units": "fixed-ticks", "value_type": "unsigned-integer-or-null" }, { "description": "Assigned Actor construction-rate modifier.", "id": "worker_rate_modifier", "required": false, "units": "basis-points", "value_type": "unsigned-integer-or-null" } ], "id": "world.construction.progress", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "query", "name": "Construction progress", "namespace": "world.construction", "owner": "game.construction", "replacement": null, "side_effects": "none", "signature": "world.construction.progress(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.construction.progress.html" }, { "authority": "read_only", "availability": "runtime API 1", "deprecated": null, "description": "Detached ScoutingOrder and Party expedition facts.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Namespace lookup is constant-time.", "examples": [ "-- Read current expeditions through world.expedition.records." ], "history": [ "1.19.0: Expedition-query namespace added for Phase 19Q9F." ], "id": "world.expedition", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [], "related": [ "world.expedition.records", "world.query" ], "returns": "The registered expedition query contracts.", "signature": "namespace world.expedition", "usage": "Use this namespace for detached expedition records. Orders, Party membership, travel, and discoveries remain with their gameplay owners." }, "errors": [], "fields": [], "id": "world.expedition", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "namespace", "name": "Expedition queries", "namespace": "world.expedition", "owner": "game.scouting-order", "replacement": null, "side_effects": "none", "signature": "namespace world.expedition", "source_location": "src/app/script_api_catalog.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.expedition.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns bounded ScoutingOrder-owned expedition state with Party, supply, route, and discovery facts.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "One bounded scouting-order scan with indexed Party, traveler, and site lookups.", "examples": [ "local expeditions = world.query(\"world.expedition.records\", {page_size = 16})" ], "history": [ "1.19.0: Expedition status records added for Phase 19Q9F." ], "id": "world.expedition.records", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [ "cursor: optional continuation cursor.", "page_size: bounded expedition-row limit." ], "related": [ "ui.action.empire.select-expedition", "world.route.known" ], "returns": "Detached records composed from ScoutingOrder, Party, and World owners, or unavailable when those owners are absent.", "signature": "world.expedition.records(filters?, cursor?, page_size?) -> query-page", "usage": "Read current scouting orders with Party membership, objective, travel progress, provisions, field condition, destination, and discovery counts." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Latest field decision or ready state.", "id": "condition", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Destination site identity.", "id": "destination_site_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Destination World X coordinate.", "id": "destination_x_meters", "required": true, "units": "meters", "value_type": "number" }, { "description": "Destination World Y coordinate.", "id": "destination_y_meters", "required": true, "units": "meters", "value_type": "number" }, { "description": "Scouting-order identity.", "id": "expedition_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Expedition leader identity.", "id": "leader_actor_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Current Party membership.", "id": "member_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Current expedition objective.", "id": "objective", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Expedition Party identity.", "id": "party_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Discovery routes returned.", "id": "reported_route_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Discovery sites returned.", "id": "reported_site_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Scouting-order revision.", "id": "revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Current expedition state.", "id": "state", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Conserved departure provisions.", "id": "supply_units", "required": true, "units": "resource-units", "value_type": "unsigned-integer" }, { "description": "Current route-segment progress.", "id": "travel_progress", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Latest expedition update.", "id": "updated_at_tick", "required": true, "units": "ticks", "value_type": "unsigned-integer" } ], "id": "world.expedition.records", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "query", "name": "Expedition records", "namespace": "world.expedition", "owner": "game.scouting-order, game.party, and sim.world", "replacement": null, "side_effects": "none", "signature": "world.expedition.records(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.expedition.records.html" }, { "authority": "read_only", "availability": "runtime API 1", "deprecated": null, "description": "Detached Faction-owned strategy and standing facts.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Namespace lookup is constant-time.", "examples": [ "-- Read standings through world.faction.standings." ], "history": [ "1.19.0: Faction-query namespace added for Phase 19Q9F." ], "id": "world.faction", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [], "related": [ "world.faction.standings", "world.query" ], "returns": "The registered Faction query contracts.", "signature": "namespace world.faction", "usage": "Use this namespace for detached Faction strategy and standing reports. Gameplay diplomacy remains owned by the Faction runtime." }, "errors": [], "fields": [], "id": "world.faction", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "namespace", "name": "Faction queries", "namespace": "world.faction", "owner": "game.faction", "replacement": null, "side_effects": "none", "signature": "namespace world.faction", "source_location": "src/app/script_api_catalog.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.faction.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns bounded Faction-owned identity, strategy, territory, and relation facts.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "One bounded Faction scan with indexed relation and topology lookups.", "examples": [ "local factions = world.query(\"world.faction.standings\", {page_size = 16})" ], "history": [ "1.19.0: Faction standings added for Phase 19Q9F." ], "id": "world.faction.standings", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [ "cursor: optional continuation cursor.", "page_size: bounded Faction-row limit." ], "related": [ "ui.action.empire.select-faction", "world.region.known" ], "returns": "Detached Faction-owned strategy and relation rows, or unavailable when the scenario has no Faction owner.", "signature": "world.faction.standings(filters?, cursor?, page_size?) -> query-page", "usage": "Read stable Faction identity, current goal, strategic intent, standing, relation pressure, territory count, and anchor site." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "First stable territory site.", "id": "anchor_site_id", "required": false, "units": null, "value_type": "stable-id-or-null" }, { "description": "Territory anchor World X coordinate.", "id": "anchor_x_meters", "required": false, "units": "meters", "value_type": "number-or-null" }, { "description": "Territory anchor World Y coordinate.", "id": "anchor_y_meters", "required": false, "units": "meters", "value_type": "number-or-null" }, { "description": "Faction identity.", "id": "faction_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Current Faction goal.", "id": "goal", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Faction display name.", "id": "name", "required": true, "units": null, "value_type": "string" }, { "description": "Current relation pressure.", "id": "relation_pressure", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Standing relative to the first stable faction.", "id": "stance", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Current retained strategic intent.", "id": "strategic_intent", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Known territory site count.", "id": "territory_site_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Latest Faction update.", "id": "updated_at_tick", "required": true, "units": "ticks", "value_type": "unsigned-integer" } ], "id": "world.faction.standings", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "query", "name": "Faction standings", "namespace": "world.faction", "owner": "game.faction and sim.world-topology", "replacement": null, "side_effects": "none", "signature": "world.faction.standings(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.faction.standings.html" }, { "authority": "read_only", "availability": "runtime API 1", "deprecated": null, "description": "Detached current Household facts and capability boundaries.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Namespace lookup is constant-time and performs no owner work.", "examples": [ "-- Access documented members through world.household.wealth." ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "world.household", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "world.household.wealth" ], "returns": "A stable namespace table containing only the documented child symbols available to this package origin.", "signature": "namespace world.household", "usage": "Use world.household only to reach its registered child contracts. The namespace itself performs no query, mutation, lifecycle transition, or drawing." }, "errors": [], "fields": [], "id": "world.household", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "namespace", "name": "Household queries", "namespace": "world.household", "owner": "game.household", "replacement": null, "side_effects": "none", "signature": "namespace world.household", "source_location": "src/app/script_api_catalog.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.household.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns detached household membership, strain, residence, and latest care facts for one actor.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "One indexed Household lookup.", "examples": [ "local household = world.query(\"world.household.for-actor\", {page_size = 1, filters = {actor_id = selected_id}})" ], "history": [ "1.3.0: Detached household membership query added for Phase 16D.", "1.8.0: Latest care kind, caregiver, recipient, material, and completion tick added for Phase 17B." ], "id": "world.household.for-actor", "manual_nodes": [ "phase.16", "phase.17", "engine-reference.extension-contract" ], "parameters": [ "filters.actor_id: required stable Actor identity.", "cursor: optional continuation cursor.", "page_size: bounded record limit." ], "related": [ "world.actor.status", "world.household.wealth", "world.query" ], "returns": "One detached household record, or a stable unavailable result when the Actor has no loaded household.", "signature": "world.household.for-actor(filters?, cursor?, page_size?) -> query-page", "usage": "Query one actor_id to inspect household identity, membership, strain, revision, assigned residence, and the latest retained meal or health-care result." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Actor identity.", "id": "actor_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Household identity.", "id": "household_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Latest retained meal or health-care kind.", "id": "latest_care_kind", "required": false, "units": null, "value_type": "enumeration-or-null" }, { "description": "Actor who received the latest retained care.", "id": "latest_care_recipient_id", "required": false, "units": null, "value_type": "stable-id-or-null" }, { "description": "Resource consumed by the latest retained care.", "id": "latest_care_resource_id", "required": false, "units": null, "value_type": "stable-id-or-null" }, { "description": "Tick when the latest retained care completed.", "id": "latest_care_tick", "required": false, "units": "ticks", "value_type": "unsigned-integer-or-null" }, { "description": "Actor who completed the latest retained care.", "id": "latest_caregiver_id", "required": false, "units": null, "value_type": "stable-id-or-null" }, { "description": "Current household member count.", "id": "member_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Assigned residence building when present.", "id": "residence_building_id", "required": false, "units": null, "value_type": "stable-id-or-null" }, { "description": "Household owner revision.", "id": "revision", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Current household strain.", "id": "strain", "required": true, "units": "basis-points", "value_type": "unsigned-integer" } ], "id": "world.household.for-actor", "introduced": { "display": "1.3.0", "major": 1, "minor": 3, "patch": 0 }, "kind": "query", "name": "Household for actor", "namespace": "world.household", "owner": "game.household", "replacement": null, "side_effects": "none", "signature": "world.household.for-actor(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.household.for-actor.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns paginated detached currency balances held by one household.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "One Household-money container lookup plus bounded content-catalog and Resource-definition visits.", "examples": [ "local money = world.query(\"world.household.wealth\", {page_size = 8, filters = {household_id = household_id}})" ], "history": [ "1.0.0: Capability boundary reserved.", "1.4.0: Physical Household money custody exposed for Phase 16D2." ], "id": "world.household.wealth", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [ "filters.household_id: required stable Household identity.", "cursor: optional continuation cursor.", "page_size: bounded currency-row limit." ], "related": [ "world.actor.wealth", "world.household.for-actor", "command.money.contribute", "world.query" ], "returns": "One detached row per authored currency in stable catalog order, including zero balances.", "signature": "world.household.wealth(filters?, cursor?, page_size?) -> query-page", "usage": "Query one household_id to read its detached currency balances and the current Resource custody revision. The returned table cannot move or reserve money." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Current household balance.", "id": "balance", "required": true, "units": "minor-currency-units", "value_type": "unsigned-integer" }, { "description": "Household-money container identity.", "id": "container_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Money-custody owner revision.", "id": "container_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Authored currency definition identity.", "id": "currency_definition_id", "required": true, "units": null, "value_type": "string" }, { "description": "Player-facing currency name.", "id": "display_name", "required": true, "units": null, "value_type": "string" }, { "description": "Household identity.", "id": "household_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Runtime Resource identity.", "id": "resource_id", "required": true, "units": null, "value_type": "stable-id" } ], "id": "world.household.wealth", "introduced": { "display": "1.4.0", "major": 1, "minor": 4, "patch": 0 }, "kind": "query", "name": "Household wealth", "namespace": "world.household", "owner": "game.resource-economy and assets.runtime-content-catalog", "replacement": null, "side_effects": "none", "signature": "world.household.wealth(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.household.wealth.html" }, { "authority": "read_only", "availability": "runtime API 1", "deprecated": null, "description": "Detached World-owned road, fence, gate, anchor, and condition facts.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Namespace lookup is constant-time and performs no owner work.", "examples": [ "-- Access retained local plans through world.infrastructure.local." ], "history": [ "1.19.0: Local infrastructure query and control namespace completed across Village Life M1 through M4." ], "id": "world.infrastructure", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [], "related": [ "world.infrastructure.local", "world.infrastructure.construction", "world.infrastructure.maintenance" ], "returns": "A stable namespace table containing the documented local-infrastructure query.", "signature": "namespace world.infrastructure", "usage": "Use world.infrastructure to inspect detached World-owned local road, fence, gate, anchor, material, access, lifecycle, and condition facts. The namespace performs no mutation or pathfinding." }, "errors": [], "fields": [], "id": "world.infrastructure", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "namespace", "name": "Local infrastructure queries", "namespace": "world.infrastructure", "owner": "sim.world", "replacement": null, "side_effects": "none", "signature": "namespace world.infrastructure", "source_location": "src/app/script_api_catalog.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.infrastructure.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns bounded Construction-owned infrastructure project, worker, Work identity, progress, resource-owner, and failure facts.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "Bounded by page size and owner-visit budgets. Construction resumes from the stable infrastructure identity cursor.", "examples": [ "local result = world.query(\"world.infrastructure.construction\", {page_size = 8})\nif result.status == \"completed\" then\n for _, project in ipairs(result.records) do\n ui.row(\"Infrastructure \" .. tostring(project.infrastructure_id), project.stage)\n end\nend" ], "history": [ "1.19.0: Physical retained road, fence, and gate construction inspection added for Village Life M2 and M3." ], "id": "world.infrastructure.construction", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [ "filters.infrastructure_id: optional positive World infrastructure identity.", "cursor: optional stable-identity continuation cursor returned by the same query.", "page_size: positive record limit capped by the host." ], "related": [ "world.infrastructure", "world.infrastructure.local", "command.infrastructure.cancel", "command.work.assign", "command.work.set-priority", "world.query" ], "returns": "A detached page containing build-or-repair purpose, project and resume stages, the World stage and condition restored on cancellation, failure cause, current worker, Work demand and job identities, source and site Resource containers, work cell, stage progress and requirements, revision, and causal ticks.", "signature": "world.infrastructure.construction(filters?, cursor?, page_size?) -> query-page", "usage": "Read retained road, fence, or gate construction progress through a bounded detached query. Use the reported project revision for cancellation and the reported Work job identity with normal priority or assignment commands; do not retain a row after its callback." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Required clearing work.", "id": "clearing_work", "required": true, "units": "work-units", "value_type": "unsigned-integer" }, { "description": "Retained work completed in the current stage.", "id": "completed_stage_work", "required": true, "units": "work-units", "value_type": "unsigned-integer" }, { "description": "Project creation tick.", "id": "created_at_tick", "required": true, "units": "ticks", "value_type": "unsigned-integer" }, { "description": "Work demand identity.", "id": "demand_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Retained terminal failure cause.", "id": "failure_cause", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Required finishing work.", "id": "finishing_work", "required": true, "units": "work-units", "value_type": "unsigned-integer" }, { "description": "World infrastructure identity.", "id": "infrastructure_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Work job identity.", "id": "job_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Required laying work.", "id": "laying_work", "required": true, "units": "work-units", "value_type": "unsigned-integer" }, { "description": "Resource stockpile container supplying the project.", "id": "material_source_container_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Build or repair.", "id": "purpose", "required": true, "units": null, "value_type": "enumeration" }, { "description": "World condition restored if the project is cancelled.", "id": "restored_world_condition", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "World stage restored if the project is cancelled.", "id": "restored_world_stage", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Stage retained across a worker handoff.", "id": "resume_stage", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Construction project revision.", "id": "revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Resource construction-site container.", "id": "site_inventory_container_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Current infrastructure-work stage.", "id": "stage", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Latest project mutation tick.", "id": "updated_at_tick", "required": true, "units": "ticks", "value_type": "unsigned-integer" }, { "description": "Infrastructure work cell X.", "id": "work_cell_x", "required": true, "units": "grid-cells", "value_type": "signed-integer" }, { "description": "Infrastructure work cell Y.", "id": "work_cell_y", "required": true, "units": "grid-cells", "value_type": "signed-integer" }, { "description": "Current resident worker.", "id": "worker_id", "required": false, "units": null, "value_type": "stable-id-or-null" } ], "id": "world.infrastructure.construction", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "query", "name": "Infrastructure construction", "namespace": "world.infrastructure", "owner": "game.infrastructure-construction", "replacement": null, "side_effects": "none", "signature": "world.infrastructure.construction(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.infrastructure.construction.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns bounded World-owned local road, fence, and gate plans with typed connection anchors, immutable geometry counts, material, access, condition, and lifecycle.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "Bounded by page size and owner-visit budgets. World resumes from the stable identity cursor without scanning preceding records.", "examples": [ "local result = world.query(\"world.infrastructure.local\", {page_size = 16})\nif result.status == \"completed\" then\n for _, item in ipairs(result.records) do\n ui.row(item.kind .. \" \" .. tostring(item.infrastructure_id), item.from_anchor_kind .. \" to \" .. tostring(item.to_anchor_kind))\n end\nend" ], "history": [ "1.19.0: Persistent local road, fence, gate, and anchor facts added for Village Life M1." ], "id": "world.infrastructure.local", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [ "filters.infrastructure_id: optional positive stable local-infrastructure identity.", "cursor: optional stable-identity continuation cursor returned by the same query.", "page_size: positive record limit capped by the host." ], "related": [ "world.infrastructure", "world.infrastructure.maintenance", "world.land.areas", "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation", "world.query" ], "returns": "A detached page containing identity, kind, typed anchors, endpoint cells, material, access policy, lifecycle stage, condition, geometry counts, revision, and causal ticks.", "signature": "world.infrastructure.local(filters?, cursor?, page_size?) -> query-page", "usage": "Read stable World-owned local infrastructure records. Typed endpoint anchors distinguish buildings, landmarks, dedicated land, settlements, and regional connections; lifecycle and condition remain detached read-only facts." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Referenced access-policy identity.", "id": "access_policy_id", "required": true, "units": null, "value_type": "string" }, { "description": "Cells in road geometry.", "id": "cell_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Current condition.", "id": "condition", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Plan creation tick.", "id": "created_at_tick", "required": true, "units": "ticks", "value_type": "unsigned-integer" }, { "description": "Edges in fence or gate geometry.", "id": "edge_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "First connection anchor identity.", "id": "from_anchor_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "First typed connection anchor.", "id": "from_anchor_kind", "required": true, "units": null, "value_type": "enumeration" }, { "description": "First anchor cell X.", "id": "from_cell_x", "required": true, "units": "grid-cells", "value_type": "signed-integer" }, { "description": "First anchor cell Y.", "id": "from_cell_y", "required": true, "units": "grid-cells", "value_type": "signed-integer" }, { "description": "Local infrastructure identity.", "id": "infrastructure_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Road, fence, or gate.", "id": "kind", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Validated physical material identity.", "id": "material_resource_id", "required": true, "units": null, "value_type": "string" }, { "description": "Whether the referenced policy permits construction access.", "id": "permits_construction_access", "required": true, "units": null, "value_type": "boolean" }, { "description": "Whether the referenced policy permits field work access.", "id": "permits_field_access", "required": true, "units": null, "value_type": "boolean" }, { "description": "Whether the referenced policy permits Actor traversal.", "id": "permits_local_travel", "required": true, "units": null, "value_type": "boolean" }, { "description": "World infrastructure revision.", "id": "revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Current infrastructure lifecycle stage.", "id": "stage", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Second connection anchor identity.", "id": "to_anchor_id", "required": false, "units": null, "value_type": "stable-id-or-null" }, { "description": "Second typed connection anchor.", "id": "to_anchor_kind", "required": false, "units": null, "value_type": "enumeration-or-null" }, { "description": "Second anchor cell X.", "id": "to_cell_x", "required": false, "units": "grid-cells", "value_type": "signed-integer-or-null" }, { "description": "Second anchor cell Y.", "id": "to_cell_y", "required": false, "units": "grid-cells", "value_type": "signed-integer-or-null" }, { "description": "Maximum road traversal-cost reduction at full condition.", "id": "travel_reduction", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Latest World mutation tick.", "id": "updated_at_tick", "required": true, "units": "ticks", "value_type": "unsigned-integer" } ], "id": "world.infrastructure.local", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "query", "name": "World local infrastructure", "namespace": "world.infrastructure", "owner": "sim.world", "replacement": null, "side_effects": "none", "signature": "world.infrastructure.local(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.infrastructure.local.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns the latest Settlement-owned repair or extension choice with the bounded World wear evidence and physical material facts that informed it.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "One Settlement lookup and a bounded candidate trace with indexed matching against the latest bounded World condition evidence.", "examples": [ "local result = world.query(\"world.infrastructure.maintenance\", {page_size = 8})\nfor _, item in ipairs(result.records) do\n ui.row(tostring(item.infrastructure_id), item.candidate_detail)\nend" ], "history": [ "1.19.0: Environment and use wear plus Settlement repair and extension evidence added for Village Life M4." ], "id": "world.infrastructure.maintenance", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [ "filters.infrastructure_id: optional positive infrastructure identity.", "cursor: optional continuation cursor.", "page_size: positive record limit capped by the host." ], "related": [ "world.infrastructure.local", "world.infrastructure.construction", "command.infrastructure.request-work", "command.work.assign", "command.work.set-priority", "world.query" ], "returns": "A detached page of Settlement-owned candidate evidence plus the autonomous maintenance cadence. The query grants no direct condition, inventory, or construction authority.", "signature": "world.infrastructure.maintenance(filters?, cursor?, page_size?) -> query-page", "usage": "Read the latest bounded Settlement choice for infrastructure repair or extension. Each candidate row explains its World stage and condition, physical material and work requirement, eligibility, score, selection, and any matching regional-pressure or active-use wear evidence from the latest condition pass." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Active paths using this infrastructure in the latest World pass.", "id": "active_move_count", "required": false, "units": "moves", "value_type": "unsigned-integer-or-null" }, { "description": "Physical material available in the selected stockpile.", "id": "available_material", "required": false, "units": "resource-units", "value_type": "unsigned-integer-or-null" }, { "description": "Candidate-specific explanation.", "id": "candidate_detail", "required": false, "units": null, "value_type": "string-or-null" }, { "description": "Condition at evaluation.", "id": "condition", "required": false, "units": "basis-points", "value_type": "unsigned-integer-or-null" }, { "description": "Condition lost during the latest World pass.", "id": "condition_loss", "required": false, "units": "basis-points", "value_type": "unsigned-integer-or-null" }, { "description": "Settlement-level explanation.", "id": "decision_detail", "required": true, "units": null, "value_type": "string" }, { "description": "Latest Settlement decision status.", "id": "decision_status", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Latest Settlement evaluation tick.", "id": "decision_tick", "required": true, "units": "ticks", "value_type": "unsigned-integer" }, { "description": "Whether all current owners permit the work.", "id": "eligible", "required": false, "units": null, "value_type": "boolean-or-null" }, { "description": "Latest regional pressure observed by World for this infrastructure.", "id": "environmental_pressure", "required": false, "units": "pressure-units", "value_type": "signed-integer-or-null" }, { "description": "Evaluated infrastructure identity, when a candidate exists.", "id": "infrastructure_id", "required": false, "units": null, "value_type": "stable-id-or-null" }, { "description": "Next autonomous condition and choice evaluation tick.", "id": "next_maintenance_tick", "required": true, "units": "ticks", "value_type": "unsigned-integer" }, { "description": "Physical material required by the evaluated work.", "id": "required_material", "required": false, "units": "resource-units", "value_type": "unsigned-integer-or-null" }, { "description": "Combined clearing, laying, and finishing work.", "id": "required_work", "required": false, "units": "work-units", "value_type": "unsigned-integer-or-null" }, { "description": "Whether Settlement selected this candidate.", "id": "selected", "required": false, "units": null, "value_type": "boolean-or-null" }, { "description": "World lifecycle stage at evaluation.", "id": "stage", "required": false, "units": null, "value_type": "enumeration-or-null" }, { "description": "Sum of retained condition, travel, field, and material contributions.", "id": "total_score", "required": false, "units": null, "value_type": "signed-integer-or-null" }, { "description": "Repair or extension.", "id": "work_kind", "required": false, "units": null, "value_type": "enumeration-or-null" } ], "id": "world.infrastructure.maintenance", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "query", "name": "Infrastructure maintenance", "namespace": "world.infrastructure", "owner": "game.settlement", "replacement": null, "side_effects": "none", "signature": "world.infrastructure.maintenance(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.infrastructure.maintenance.html" }, { "authority": "read_only", "availability": "runtime API 1", "deprecated": null, "description": "Detached current Work-owned job facts.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Namespace lookup is constant-time and performs no owner work.", "examples": [ "-- Access documented members through world.job.info." ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "world.job", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "world.job.info" ], "returns": "A stable namespace table containing only the documented child symbols available to this package origin.", "signature": "namespace world.job", "usage": "Use world.job only to reach its registered child contracts. The namespace itself performs no query, mutation, lifecycle transition, or drawing." }, "errors": [], "fields": [], "id": "world.job", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "namespace", "name": "Job queries", "namespace": "world.job", "owner": "game.work-lifecycle", "replacement": null, "side_effects": "none", "signature": "namespace world.job", "source_location": "src/app/script_api_catalog.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.job.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns one detached work job selected by stable job identity.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "Bounded by page size, per-package query budget, and the owning snapshot builder; results are detached before Lua receives them.", "examples": [ "local result = world.query(\"world.job.info\", {page_size = 16})\nif result.status == \"completed\" then\n for _, record in ipairs(result.records) do\n -- Render or inspect detached record fields here.\n end\nend" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "world.job.info", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [ "filters: optional table of query-specific stable IDs and bounded selectors.", "cursor: optional opaque continuation cursor returned by the same query.", "page_size: optional positive record limit capped by the host." ], "related": [ "world.job", "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation", "world.query" ], "returns": "A detached query page with status, records, continuation metadata, and a stable diagnostic when the request cannot complete.", "signature": "world.job.info(filters?, cursor?, page_size?) -> query-page", "usage": "Call this query through world.query with the stable ID world.job.info. Consume detached records during the current callback and use the returned cursor for bounded continuation." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Claiming actor when present.", "id": "claimant_actor_id", "required": false, "units": null, "value_type": "stable-id-or-null" }, { "description": "Parent demand identity.", "id": "demand_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Job identity.", "id": "job_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Durable player-priority contribution.", "id": "player_priority", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Owner revision.", "id": "revision", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Current job state.", "id": "state", "required": true, "units": null, "value_type": "enumeration" } ], "id": "world.job.info", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "query", "name": "Job information", "namespace": "world.job", "owner": "game.work-lifecycle", "replacement": null, "side_effects": "none", "signature": "world.job.info(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.job.info.html" }, { "authority": "read_only", "availability": "runtime API 1", "deprecated": null, "description": "Detached World-owned land area, condition, crop, and lifecycle facts.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Namespace lookup is constant-time and performs no owner work.", "examples": [ "-- Access retained land cells through world.land.areas." ], "history": [ "1.19.0: World land query namespace added for Village Life L1." ], "id": "world.land", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [], "related": [ "world.land.areas" ], "returns": "A stable namespace table containing the documented land-area query available to this package origin.", "signature": "namespace world.land", "usage": "Use world.land to reach detached facts from World-owned irregular land areas. The namespace performs no mutation, lifecycle transition, or drawing." }, "errors": [], "fields": [], "id": "world.land", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "namespace", "name": "Land queries", "namespace": "world.land", "owner": "sim.world", "replacement": null, "side_effects": "none", "signature": "namespace world.land", "source_location": "src/app/script_api_catalog.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.land.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns stable cell rows for World-owned irregular land areas and their retained condition.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "Bounded by page size and the package query and owner-visit budgets; the detached World area snapshot is scanned in canonical order.", "examples": [ "local result = world.query(\"world.land.areas\", {page_size = 32})\nif result.status == \"completed\" then\n for _, cell in ipairs(result.records) do\n ui.row(\"Land \" .. tostring(cell.area_id), cell.land_use_definition_id .. \" / \" .. cell.lifecycle_stage)\n end\nend" ], "history": [ "1.19.0: Detached irregular World land cells and retained crop lifecycle added for Village Life L1." ], "id": "world.land.areas", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [ "filters.area_id: optional positive stable land-area identity.", "cursor: optional continuation cursor returned by the same query.", "page_size: positive record limit capped by the host." ], "related": [ "world.land", "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation", "world.query" ], "returns": "A detached page containing one row per retained area cell in stable area and cell order, with area identity, total cell count, land use, condition, optional crop, lifecycle stage, revision, and causal ticks.", "signature": "world.land.areas(filters?, cursor?, page_size?) -> query-page", "usage": "Read stable cell rows from World-owned irregular land areas. Each row repeats the area's validated land-use identity, retained condition, crop lifecycle, revision, and causal ticks without changing land. Active crop rows also expose physical work, forecast, recurring-cycle, worker-choice, replant, and blockage facts retained by Farming." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "World land area identity.", "id": "area_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Connected cells in the area.", "id": "cell_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "World-grid cell X coordinate.", "id": "cell_x", "required": true, "units": "grid-cells", "value_type": "signed-integer" }, { "description": "World-grid cell Y coordinate.", "id": "cell_y", "required": true, "units": "grid-cells", "value_type": "signed-integer" }, { "description": "Site currently controlling the area, independent of its dedication.", "id": "controlling_site_id", "required": false, "units": null, "value_type": "stable-id-or-null" }, { "description": "Current retained physical conversion stage.", "id": "conversion_stage", "required": false, "units": null, "value_type": "enumeration-or-null" }, { "description": "Work retained in the current conversion stage.", "id": "conversion_work_completed", "required": false, "units": "work-units", "value_type": "unsigned-integer-or-null" }, { "description": "Work required by the current conversion stage.", "id": "conversion_work_required", "required": false, "units": "work-units", "value_type": "unsigned-integer-or-null" }, { "description": "Resident currently committed to conversion work.", "id": "conversion_worker_id", "required": false, "units": null, "value_type": "stable-id-or-null" }, { "description": "Current retained land cover.", "id": "cover", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Area creation tick.", "id": "created_at_tick", "required": true, "units": "ticks", "value_type": "unsigned-integer" }, { "description": "Current crop identity.", "id": "crop_definition_id", "required": false, "units": null, "value_type": "string-or-null" }, { "description": "Settlement site responsible for the dedicated area.", "id": "dedicated_site_id", "required": false, "units": null, "value_type": "stable-id-or-null" }, { "description": "Current whole-area land dedication.", "id": "dedication", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Current retained depletion.", "id": "depletion", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Direct reason current settlement food need cannot advance this area.", "id": "farming_blockage_reason", "required": false, "units": null, "value_type": "string-or-null" }, { "description": "Direct reason for the latest crop, area, and resident choice.", "id": "farming_choice_reason", "required": false, "units": null, "value_type": "string-or-null" }, { "description": "Completed harvest or recovery cycles retained for this area.", "id": "farming_completed_cycles", "required": false, "units": "cycles", "value_type": "unsigned-integer-or-null" }, { "description": "Direct explanation for the latest crop forecast or outcome.", "id": "farming_forecast_reason", "required": false, "units": null, "value_type": "string-or-null" }, { "description": "Latest deterministic crop yield forecast.", "id": "farming_forecast_yield", "required": false, "units": "basis-points", "value_type": "unsigned-integer-or-null" }, { "description": "Tick when the current growth interval can advance.", "id": "farming_growth_ready_tick", "required": false, "units": "ticks", "value_type": "unsigned-integer-or-null" }, { "description": "Last resident selected for this crop cycle.", "id": "farming_last_worker_id", "required": false, "units": null, "value_type": "stable-id-or-null" }, { "description": "Tick when retained land becomes eligible for another crop cycle.", "id": "farming_next_replant_tick", "required": false, "units": "ticks", "value_type": "unsigned-integer-or-null" }, { "description": "Latest retained crop forecast or outcome.", "id": "farming_outcome", "required": false, "units": null, "value_type": "enumeration-or-null" }, { "description": "Current retained crop-cycle stage.", "id": "farming_stage", "required": false, "units": null, "value_type": "enumeration-or-null" }, { "description": "Work retained in the current crop stage.", "id": "farming_work_completed", "required": false, "units": "work-units", "value_type": "unsigned-integer-or-null" }, { "description": "Work required by the current crop stage.", "id": "farming_work_required", "required": false, "units": "work-units", "value_type": "unsigned-integer-or-null" }, { "description": "Resident currently committed to crop work.", "id": "farming_worker_id", "required": false, "units": null, "value_type": "stable-id-or-null" }, { "description": "Current fertility.", "id": "fertility", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Validated immutable land-use identity.", "id": "land_use_definition_id", "required": true, "units": null, "value_type": "string" }, { "description": "Current crop or fallow lifecycle stage.", "id": "lifecycle_stage", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Current moisture.", "id": "moisture", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Whether this cell is a preferred gate or road access cell.", "id": "preferred_access", "required": true, "units": null, "value_type": "boolean" }, { "description": "Preferred access cells retained for the whole area.", "id": "preferred_access_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Current retained preparation state.", "id": "preparation", "required": true, "units": null, "value_type": "enumeration" }, { "description": "World land area revision.", "id": "revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Current lifecycle-stage start tick.", "id": "stage_started_at_tick", "required": true, "units": "ticks", "value_type": "unsigned-integer" }, { "description": "Latest area mutation tick.", "id": "updated_at_tick", "required": true, "units": "ticks", "value_type": "unsigned-integer" } ], "id": "world.land.areas", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "query", "name": "World land areas", "namespace": "world.land", "owner": "sim.world", "replacement": null, "side_effects": "none", "signature": "world.land.areas(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.land.areas.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns one bounded derived enclosure record per World land area from authoritative area boundaries and operational fence and gate geometry.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "Bounded by the page size and current retained land and infrastructure records; results are emitted in stable area identity order.", "examples": [ "local result = world.query(\"world.land.enclosures\", {page_size = 8})\nif result.status == \"completed\" then\n for _, area in ipairs(result.records) do\n ui.row(\"Field \" .. tostring(area.area_id), area.enclosed and \"enclosed\" or \"open\")\n end\nend" ], "history": [ "1.19.0: Whole-area fence, gate, and field-access inspection added for Village Life M3." ], "id": "world.land.enclosures", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [ "filters.area_id: optional positive stable land-area identity.", "cursor: optional stable area-identity continuation cursor returned by the same query.", "page_size: positive record limit capped by the host." ], "related": [ "world.land.areas", "world.infrastructure.local", "command.infrastructure.set-access-policy", "world.query" ], "returns": "A detached page containing whole-boundary edge, fence, gate, and open-edge counts; enclosure and field-access results; referenced gate-policy information; and a derived infrastructure revision fingerprint.", "signature": "world.land.enclosures(filters?, cursor?, page_size?) -> query-page", "usage": "Read one detached whole-area enclosure summary derived from the World land boundary and current operational fence and gate geometry. Use the enclosure and field-access fields to explain whether the complete area is protected and usable; the query cannot change infrastructure or access." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Distinct access policies referenced by boundary gates.", "id": "access_policy_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "World land area identity.", "id": "area_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Edges in the whole area boundary.", "id": "boundary_edge_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Whether every boundary edge is closed by a fence or gate.", "id": "enclosed", "required": true, "units": null, "value_type": "boolean" }, { "description": "Boundary edges covered by fences.", "id": "fence_edge_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Whether the enclosed area has a gate policy permitting field access.", "id": "field_accessible", "required": true, "units": null, "value_type": "boolean" }, { "description": "Boundary edges covered by gates.", "id": "gate_edge_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Derived revision fingerprint of current boundary infrastructure.", "id": "infrastructure_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Boundary edges with no current enclosure.", "id": "open_edge_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "First stable gate access-policy identity, when present.", "id": "primary_access_policy_id", "required": false, "units": null, "value_type": "string-or-null" } ], "id": "world.land.enclosures", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "query", "name": "World land enclosures", "namespace": "world.land", "owner": "sim.world", "replacement": null, "side_effects": "none", "signature": "world.land.enclosures(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.land.enclosures.html" }, { "authority": "read_only", "availability": "runtime API 1", "deprecated": null, "description": "Detached World-owned landscape clusters and feature placement facts.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Namespace lookup is constant-time and performs no owner work.", "examples": [ "-- Access retained landscape placement through world.landscape.features." ], "history": [ "1.19.0: World landscape query namespace added for Village Life N1." ], "id": "world.landscape", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [], "related": [ "world.landscape.features" ], "returns": "A stable namespace table containing the documented landscape feature query.", "signature": "namespace world.landscape", "usage": "Use world.landscape to inspect detached World-owned feature identities, clusters, cells, density, revisions, and stable variation inputs. The namespace performs no placement, lifecycle mutation, or render-frame selection." }, "errors": [], "fields": [], "id": "world.landscape", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "namespace", "name": "Landscape queries", "namespace": "world.landscape", "owner": "sim.world", "replacement": null, "side_effects": "none", "signature": "namespace world.landscape", "source_location": "src/app/script_api_catalog.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.landscape.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns bounded World-owned landscape identities, cluster membership, placement, and stable variation inputs without exposing render frame choices as simulation truth.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "Bounded by page size and package query and owner-visit budgets. World resumes from the stable feature identity cursor without activating cold chunks.", "examples": [ "local result = world.query(\"world.landscape.features\", {page_size = 32})\nif result.status == \"completed\" then\n for _, feature in ipairs(result.records) do\n ui.row(feature.appearance_family_id, tostring(feature.cell_x) .. \", \" .. tostring(feature.cell_y))\n end\nend" ], "history": [ "1.19.0: Retained cluster placement and deterministic appearance input query added for Village Life N1.", "1.19.1: Lifecycle policy, kind, stage, maturity, renewal, and harvest facts added for Village Life N2." ], "id": "world.landscape.features", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [ "filters.feature_id: optional positive stable World landscape feature identity.", "cursor: optional stable feature-identity continuation cursor returned by the same query.", "page_size: positive record limit capped by the host." ], "related": [ "world.landscape", "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation", "world.query" ], "returns": "A detached page containing feature and cluster identities, current family and lifecycle-policy identities, kind, stage, maturity, renewal and harvest ticks, canonical cell, density, revisions, creation tick, and stable variation key.", "signature": "world.landscape.features(filters?, cursor?, page_size?) -> query-page", "usage": "Read retained World landscape placement and lifecycle in stable feature order. Current appearance, lifecycle policy, kind, stage, maturity, renewal, and harvest facts come from World state; the variation key remains only a repeatable input for derived presentation. The query grants no mutation, atlas, or frame-choice authority." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Current validated landscape appearance-family identity.", "id": "appearance_family_id", "required": true, "units": null, "value_type": "string" }, { "description": "World-grid cell X coordinate.", "id": "cell_x", "required": true, "units": "grid-cells", "value_type": "signed-integer" }, { "description": "World-grid cell Y coordinate.", "id": "cell_y", "required": true, "units": "grid-cells", "value_type": "signed-integer" }, { "description": "World landscape cluster identity.", "id": "cluster_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "World landscape cluster revision.", "id": "cluster_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Cluster creation tick.", "id": "created_at_tick", "required": true, "units": "ticks", "value_type": "unsigned-integer" }, { "description": "Authored cluster density.", "id": "density", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "World landscape feature identity.", "id": "feature_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "World landscape feature revision.", "id": "feature_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Tree, bush, or rock.", "id": "kind", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Most recent committed harvest tick.", "id": "last_harvested_at_tick", "required": false, "units": "ticks", "value_type": "unsigned-integer-or-null" }, { "description": "Immutable lifecycle and yield policy identity.", "id": "lifecycle_policy_id", "required": true, "units": null, "value_type": "string" }, { "description": "Current feature maturity.", "id": "maturity", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Causal regrowth eligibility tick when the harvested feature is renewable.", "id": "regrowth_due_tick", "required": false, "units": "ticks", "value_type": "unsigned-integer-or-null" }, { "description": "Standing, stump, or cleared.", "id": "stage", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Stable derived input used to choose among validated appearance frames.", "id": "variation_key", "required": true, "units": null, "value_type": "unsigned-integer" } ], "id": "world.landscape.features", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "query", "name": "World landscape features", "namespace": "world.landscape", "owner": "sim.world", "replacement": null, "side_effects": "none", "signature": "world.landscape.features(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.landscape.features.html" }, { "authority": "read_only", "availability": "runtime API 1", "deprecated": null, "description": "Detached current Work-owned assignment order facts.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Namespace lookup is constant-time and performs no owner work.", "examples": [ "-- Access documented members through world.order.info." ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "world.order", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "world.order.info" ], "returns": "A stable namespace table containing only the documented child symbols available to this package origin.", "signature": "namespace world.order", "usage": "Use world.order only to reach its registered child contracts. The namespace itself performs no query, mutation, lifecycle transition, or drawing." }, "errors": [], "fields": [], "id": "world.order", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "namespace", "name": "Order queries", "namespace": "world.order", "owner": "game.work-lifecycle", "replacement": null, "side_effects": "none", "signature": "namespace world.order", "source_location": "src/app/script_api_catalog.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.order.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns one detached assignment order selected by stable order identity.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "Bounded by page size, per-package query budget, and the owning snapshot builder; results are detached before Lua receives them.", "examples": [ "local result = world.query(\"world.order.info\", {page_size = 16})\nif result.status == \"completed\" then\n for _, record in ipairs(result.records) do\n -- Render or inspect detached record fields here.\n end\nend" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "world.order.info", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [ "filters: optional table of query-specific stable IDs and bounded selectors.", "cursor: optional opaque continuation cursor returned by the same query.", "page_size: optional positive record limit capped by the host." ], "related": [ "world.order", "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation", "world.query" ], "returns": "A detached query page with status, records, continuation metadata, and a stable diagnostic when the request cannot complete.", "signature": "world.order.info(filters?, cursor?, page_size?) -> query-page", "usage": "Call this query through world.query with the stable ID world.order.info. Consume detached records during the current callback and use the returned cursor for bounded continuation." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Recipient actor identity.", "id": "actor_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Assigned job identity.", "id": "job_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Assignment order identity.", "id": "order_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Owner revision.", "id": "revision", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Current order state.", "id": "state", "required": true, "units": null, "value_type": "enumeration" } ], "id": "world.order.info", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "query", "name": "Order information", "namespace": "world.order", "owner": "game.work-lifecycle", "replacement": null, "side_effects": "none", "signature": "world.order.info(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.order.info.html" }, { "authority": "read_only", "availability": "runtime API 1", "deprecated": null, "description": "Detached authored alternatives and retained autonomous project decisions.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Namespace lookup is constant-time and performs no owner work.", "examples": [ "-- Inspect authored alternatives with world.project.alternatives and the latest autonomous decision with world.project.proposals." ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "world.project", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "world.project.alternatives", "world.project.proposals" ], "returns": "A stable namespace table containing only the documented child symbols available to this package origin.", "signature": "namespace world.project", "usage": "Use world.project only to reach its registered child contracts. The namespace itself performs no query, mutation, lifecycle transition, or drawing." }, "errors": [], "fields": [], "id": "world.project", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "namespace", "name": "Project queries", "namespace": "world.project", "owner": "game.settlement", "replacement": null, "side_effects": "none", "signature": "namespace world.project", "source_location": "src/app/script_api_catalog.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.project.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns the settlement's authored building alternatives and immutable construction facts without selecting or proposing a project.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "One bounded content-catalog visit per alternative and required material.", "examples": [ "local projects = world.query(\"world.project.alternatives\", {page_size = 8})" ], "history": [ "1.3.0: Authored settlement project alternatives exposed for Phase 16D." ], "id": "world.project.alternatives", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [ "cursor: optional continuation cursor.", "page_size: bounded alternative count." ], "related": [ "world.project.proposals", "world.query" ], "returns": "Detached project alternatives with building identity, name, function, material summary, work requirement, capacity, and footprint size.", "signature": "world.project.alternatives(filters?, cursor?, page_size?) -> query-page", "usage": "List the active scenario's authored building alternatives in authored order. This query exposes immutable choices but does not propose, score, or select a project." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Authored base capacity.", "id": "base_capacity", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Authored one-based choice order.", "id": "choice_ordinal", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Building definition identity.", "id": "definition_id", "required": true, "units": null, "value_type": "string" }, { "description": "Player-facing building name.", "id": "display_name", "required": true, "units": null, "value_type": "string" }, { "description": "Occupied footprint cell count.", "id": "footprint_cells", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Bounding footprint height.", "id": "footprint_height_cells", "required": true, "units": "World-grid cells", "value_type": "unsigned-integer" }, { "description": "Bounding footprint width.", "id": "footprint_width_cells", "required": true, "units": "World-grid cells", "value_type": "unsigned-integer" }, { "description": "Building function.", "id": "function", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Required material summary.", "id": "materials", "required": true, "units": null, "value_type": "string" }, { "description": "Required physical work.", "id": "required_work_units", "required": true, "units": "work-units", "value_type": "unsigned-integer" } ], "id": "world.project.alternatives", "introduced": { "display": "1.3.0", "major": 1, "minor": 3, "patch": 0 }, "kind": "query", "name": "Authored project alternatives", "namespace": "world.project", "owner": "game.runtime-settlement-definition and assets.runtime-content-catalog", "replacement": null, "side_effects": "none", "signature": "world.project.alternatives(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.project.alternatives.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns the latest retained autonomous project decision and its complete bounded candidate trace for one settlement.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "One Settlement lookup plus one owner visit per returned candidate, bounded by page size and the calling package's query budgets.", "examples": [ "local result = world.query(\"world.project.proposals\", {\n page_size = 8,\n filters = {settlement_id = settlement.settlement_id}\n})\nif result.status == \"completed\" then\n for _, proposal in ipairs(result.records) do\n local outcome = proposal.eligible and tostring(proposal.total_score)\n or proposal.eligibility_detail\n ui.row(proposal.building_definition_id, outcome)\n end\nend" ], "history": [ "1.0.0: Placeholder capability contract published with the Phase 14 registry.", "1.5.0: Retained autonomous project decisions and complete candidate traces implemented for Phase 16E.", "1.5.0: Added the selected project's retained terminal outcome and reopened decision cadence for Phase 16F." ], "id": "world.project.proposals", "manual_nodes": [ "phase.14", "phase.16", "engine-reference.extension-contract" ], "parameters": [ "filters.settlement_id: required positive Settlement identity.", "cursor: optional continuation cursor indexing the canonical candidate order.", "page_size: optional positive candidate-row limit capped by the host." ], "related": [ "world.project", "world.project.alternatives", "world.settlement.for-actor", "world.construction.active", "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation", "world.query" ], "returns": "A detached candidate page. Decision-level and optional terminal-outcome fields are repeated on every row so continuation pages remain self-describing. Returns capability-unavailable when the Settlement owner or its latest decision is absent.", "signature": "world.project.proposals(filters?, cursor?, page_size?) -> query-page", "usage": "Query one settlement's latest retained autonomous project decision. Each detached row contains one candidate's hard-gate result and complete fixed-point score plus the shared decision status, explanation, source Settlement revision, selected Construction identity, retained terminal outcome when present, next decision tick, tuning version, useful-project threshold, candidate and consideration counts, and the Building and stockpile owner visits used to compose the facts. Follow next_cursor to inspect every retained candidate." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Candidate building definition identity.", "id": "building_definition_id", "required": true, "units": null, "value_type": "string" }, { "description": "Building owner facts visited while composing the decision.", "id": "building_visit_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Stable authored proposal identity.", "id": "candidate_id", "required": true, "units": null, "value_type": "string" }, { "description": "Housing or storage pressure score contribution.", "id": "capacity_pressure_contribution", "required": true, "units": "basis-points", "value_type": "signed-integer" }, { "description": "Fixed-point score components evaluated by the reasoner.", "id": "consideration_evaluation_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Owner-retained decision explanation.", "id": "decision_detail", "required": true, "units": null, "value_type": "string" }, { "description": "Selected or no-selection result.", "id": "decision_status", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Fixed tick evaluated.", "id": "decision_tick", "required": true, "units": "fixed-ticks", "value_type": "unsigned-integer" }, { "description": "Specific eligibility or rejection reason.", "id": "eligibility_detail", "required": true, "units": null, "value_type": "string" }, { "description": "Whether the candidate passed every hard gate.", "id": "eligible", "required": true, "units": null, "value_type": "boolean" }, { "description": "Candidates that passed every hard eligibility gate.", "id": "eligible_candidate_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Lower-labor-cost score contribution.", "id": "inverse_labor_cost_contribution", "required": true, "units": "basis-points", "value_type": "signed-integer" }, { "description": "Material-readiness score contribution.", "id": "material_readiness_contribution", "required": true, "units": "basis-points", "value_type": "signed-integer" }, { "description": "Required useful-project score.", "id": "minimum_score", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Next fixed tick when autonomous planning may run.", "id": "next_project_decision_tick", "required": true, "units": "fixed-ticks", "value_type": "unsigned-integer" }, { "description": "Building definition retained with the terminal outcome.", "id": "project_outcome_building_definition_id", "required": false, "units": null, "value_type": "string-or-null" }, { "description": "Building identity retained with the terminal outcome.", "id": "project_outcome_building_id", "required": false, "units": null, "value_type": "stable-id-or-null" }, { "description": "Retained terminal cause of the selected project.", "id": "project_outcome_cause", "required": false, "units": null, "value_type": "enumeration-or-null" }, { "description": "Construction identity retained with the terminal outcome.", "id": "project_outcome_construction_id", "required": false, "units": null, "value_type": "stable-id-or-null" }, { "description": "Construction revision observed at the terminal outcome.", "id": "project_outcome_construction_revision", "required": false, "units": null, "value_type": "revision-or-null" }, { "description": "Tick when Settlement retained the terminal outcome.", "id": "project_outcome_recorded_at_tick", "required": false, "units": "fixed-ticks", "value_type": "unsigned-integer-or-null" }, { "description": "Retained terminal status of the selected project.", "id": "project_outcome_status", "required": false, "units": null, "value_type": "enumeration-or-null" }, { "description": "Whether this candidate won the decision.", "id": "selected", "required": true, "units": null, "value_type": "boolean" }, { "description": "Construction created by the selected proposal.", "id": "selected_construction_id", "required": false, "units": null, "value_type": "stable-id-or-null" }, { "description": "Settlement identity.", "id": "settlement_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Current Settlement owner revision.", "id": "settlement_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Settlement revision evaluated by the reasoner.", "id": "source_settlement_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Stockpile owner facts visited while composing the decision.", "id": "stockpile_visit_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Candidate's complete fixed-point score.", "id": "total_score", "required": true, "units": "basis-points", "value_type": "signed-integer" }, { "description": "Fixed-point reasoner tuning version.", "id": "tuning_version", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Candidates visited by the bounded reasoner.", "id": "visited_candidate_count", "required": true, "units": null, "value_type": "unsigned-integer" } ], "id": "world.project.proposals", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "query", "name": "Project proposals", "namespace": "world.project", "owner": "game.settlement", "replacement": null, "side_effects": "none", "signature": "world.project.proposals(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.project.proposals.html" }, { "authority": "read_only", "availability": "Phase 14 package callbacks", "deprecated": null, "description": "Executes one registered detached query.", "determinism": "Host-created package identity and per-callback budgets.", "documentation": { "cost": "Constant-size contract lookup or bounded retained-record access.", "examples": [ "local result = world.query(\"world.resource.counts\", {page_size = 16})" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "world.query", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [ "query_id: stable ID of a registered query.", "request: optional table containing filters, cursor, and page_size." ], "related": [ "world", "error.invalid-query", "error.query-budget-exhausted" ], "returns": "A detached query result table with status, records, cursor, detail, and bounded work metadata.", "signature": "world.query(query_id, request?) -> query_result", "usage": "Use the stable query ID and a bounded request table. Handle completed, unavailable, exhausted, and invalid results explicitly." }, "errors": [ "error.invalid-query", "error.query-budget-exhausted" ], "fields": [], "id": "world.query", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "function", "name": "query", "namespace": "world", "owner": "app.ScriptPackageHost", "replacement": null, "side_effects": "none", "signature": "world.query(query_id, request?) -> query_result", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.query.html" }, { "authority": "read_only", "availability": "runtime API 1", "deprecated": null, "description": "Detached observer-known regional environment facts.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Namespace lookup is constant-time.", "examples": [ "-- Read known regions through world.region.known." ], "history": [ "1.19.0: Region-query namespace added for Phase 19Q9F." ], "id": "world.region", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [], "related": [ "world.region.known", "world.query" ], "returns": "The registered region query contracts.", "signature": "namespace world.region", "usage": "Use this namespace for observer-bounded regional environment reports. It has no independent state or mutation authority." }, "errors": [], "fields": [], "id": "world.region", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "namespace", "name": "Regional environment queries", "namespace": "world.region", "owner": "game.observer-knowledge", "replacement": null, "side_effects": "none", "signature": "namespace world.region", "source_location": "src/app/script_api_catalog.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.region.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns the observer's bounded current or stale regional environment reports.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "One bounded ObserverKnowledge scan and indexed World environment lookups.", "examples": [ "local regions = world.query(\"world.region.known\", {page_size = 16})" ], "history": [ "1.19.0: Observer-bounded region reports added for Phase 19Q9F." ], "id": "world.region.known", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [ "cursor: optional continuation cursor.", "page_size: bounded region-row limit." ], "related": [ "world.route.known", "world.resource.known" ], "returns": "Detached region rows limited to retained observer reports.", "signature": "world.region.known(filters?, cursor?, page_size?) -> query-page", "usage": "Read discovered regions with knowledge confidence, biome, weather, and environmental pressure for the Empire view." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Reported regional biome.", "id": "biome", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Report confidence.", "id": "confidence", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Reported environmental pressure.", "id": "environmental_pressure", "required": true, "units": "pressure-units", "value_type": "signed-integer" }, { "description": "Current or stale knowledge state.", "id": "knowledge", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Source observation tick.", "id": "observed_at_tick", "required": true, "units": "ticks", "value_type": "unsigned-integer" }, { "description": "Region identity.", "id": "region_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Reported regional weather.", "id": "weather", "required": true, "units": null, "value_type": "enumeration" } ], "id": "world.region.known", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "query", "name": "Known regions", "namespace": "world.region", "owner": "game.observer-knowledge", "replacement": null, "side_effects": "none", "signature": "world.region.known(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.region.known.html" }, { "authority": "read_only", "availability": "runtime API 1", "deprecated": null, "description": "Detached current resource totals and reservation facts.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Namespace lookup is constant-time and performs no owner work.", "examples": [ "-- Access documented members through world.resource.counts." ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "world.resource", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "world.resource.counts" ], "returns": "A stable namespace table containing only the documented child symbols available to this package origin.", "signature": "namespace world.resource", "usage": "Use world.resource only to reach its registered child contracts. The namespace itself performs no query, mutation, lifecycle transition, or drawing." }, "errors": [], "fields": [], "id": "world.resource", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "namespace", "name": "Resource queries", "namespace": "world.resource", "owner": "game.resource-economy", "replacement": null, "side_effects": "none", "signature": "namespace world.resource", "source_location": "src/app/script_api_catalog.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.resource.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns paginated detached world-wide totals for registered resources.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "Bounded by page size, the Resource owner count window, one content-catalog lookup per returned row, and the package query budget.", "examples": [ "local result = world.query(\"world.resource.counts\", {page_size = 16})\nif result.status == \"completed\" then\n for _, resource in ipairs(result.records) do\n ui.row(resource.display_name, tostring(resource.total))\n end\nend" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry.", "1.5.0: Added the authored display_name field for normal interface labels.", "1.5.0: Clarified that totals cover the complete loaded Resource owner rather than one Settlement." ], "id": "world.resource.counts", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [ "filters.resource_id: optional stable Resource identity.", "cursor: optional opaque continuation cursor returned by the same query.", "page_size: positive record limit capped by the host." ], "related": [ "world.resource", "world.settlement.resources", "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation", "world.query" ], "returns": "Detached world-wide resource rows with stable identity, authored key and display name, plus total, available, reserved, in-transit, consumed, and produced quantities.", "signature": "world.resource.counts(filters?, cursor?, page_size?) -> query-page", "usage": "Read bounded world-wide quantities in stable Resource order. Use display_name for player-facing labels and key or resource_id for durable logic. Use world.settlement.resources when an interface specifically claims to show one settlement's stores." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Unreserved quantity.", "id": "available", "required": true, "units": "resource-units", "value_type": "unsigned-integer" }, { "description": "Cumulative consumed quantity.", "id": "consumed", "required": true, "units": "resource-units", "value_type": "unsigned-integer" }, { "description": "Player-facing authored resource name.", "id": "display_name", "required": true, "units": null, "value_type": "string" }, { "description": "Quantity in transit.", "id": "in_transit", "required": true, "units": "resource-units", "value_type": "unsigned-integer" }, { "description": "Authored resource key.", "id": "key", "required": true, "units": null, "value_type": "string" }, { "description": "Cumulative produced quantity.", "id": "produced", "required": true, "units": "resource-units", "value_type": "unsigned-integer" }, { "description": "Reserved quantity.", "id": "reserved", "required": true, "units": "resource-units", "value_type": "unsigned-integer" }, { "description": "Resource identity.", "id": "resource_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Current quantity in containers.", "id": "total", "required": true, "units": "resource-units", "value_type": "unsigned-integer" } ], "id": "world.resource.counts", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "query", "name": "Resource counts", "namespace": "world.resource", "owner": "game.resource-economy", "replacement": null, "side_effects": "none", "signature": "world.resource.counts(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.resource.counts.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns bounded renewable-resource reports with their known site and map position.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "One bounded ObserverKnowledge resource scan.", "examples": [ "local sources = world.query(\"world.resource.known\", {page_size = 32})" ], "history": [ "1.19.0: Observer-bounded resource reports added for Phase 19Q9F." ], "id": "world.resource.known", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [ "cursor: optional continuation cursor.", "page_size: bounded source-row limit." ], "related": [ "world.resource", "world.region.known", "world.query" ], "returns": "Detached resource-source rows limited to retained observer knowledge.", "signature": "world.resource.known(filters?, cursor?, page_size?) -> query-page", "usage": "Read observer-known renewable source reports with site, kind, available quantity, capacity, and confidence." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Reported available quantity.", "id": "available", "required": true, "units": "resource-units", "value_type": "unsigned-integer" }, { "description": "Reported source capacity.", "id": "capacity", "required": true, "units": "resource-units", "value_type": "unsigned-integer" }, { "description": "Report confidence.", "id": "confidence", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Reported renewable resource kind.", "id": "kind", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Current or stale knowledge state.", "id": "knowledge", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Reported site identity.", "id": "site_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Reported World X coordinate.", "id": "site_x_meters", "required": true, "units": "meters", "value_type": "number" }, { "description": "Reported World Y coordinate.", "id": "site_y_meters", "required": true, "units": "meters", "value_type": "number" }, { "description": "Renewable source identity.", "id": "source_id", "required": true, "units": null, "value_type": "stable-id" } ], "id": "world.resource.known", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "query", "name": "Known regional resources", "namespace": "world.resource", "owner": "game.observer-knowledge and sim.world-topology", "replacement": null, "side_effects": "none", "signature": "world.resource.known(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.resource.known.html" }, { "authority": "read_only", "availability": "runtime API 1", "deprecated": null, "description": "Detached observer-known route and endpoint facts.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Namespace lookup is constant-time.", "examples": [ "-- Read discovered routes through world.route.known." ], "history": [ "1.19.0: Route-query namespace added for Phase 19Q9F." ], "id": "world.route", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [], "related": [ "world.route.known", "world.query" ], "returns": "The registered route query contracts.", "signature": "namespace world.route", "usage": "Use this namespace for observer-bounded route reports. It exposes no hidden topology and performs no mutation." }, "errors": [], "fields": [], "id": "world.route", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "namespace", "name": "Regional route queries", "namespace": "world.route", "owner": "game.observer-knowledge", "replacement": null, "side_effects": "none", "signature": "namespace world.route", "source_location": "src/app/script_api_catalog.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.route.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns the observer's bounded route knowledge with topology endpoints and current reported confidence, pressure, and danger.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "One bounded ObserverKnowledge scan and indexed topology lookups.", "examples": [ "local routes = world.query(\"world.route.known\", {page_size = 32})" ], "history": [ "1.19.0: Observer-bounded route reports added for Phase 19Q9F." ], "id": "world.route.known", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [ "cursor: optional continuation cursor.", "page_size: bounded route-row limit." ], "related": [ "world.region.known", "ui.action.empire.select-route" ], "returns": "Detached route rows limited to the observer's current or stale knowledge.", "signature": "world.route.known(filters?, cursor?, page_size?) -> query-page", "usage": "Read discovered route segments with observer knowledge state, endpoints, coordinates, pressure, and danger for regional presentation." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Latest report confidence.", "id": "confidence", "required": false, "units": "basis-points", "value_type": "unsigned-integer-or-null" }, { "description": "Latest reported route danger.", "id": "danger", "required": false, "units": "danger-units", "value_type": "signed-integer-or-null" }, { "description": "Knowledge evaluation tick.", "id": "evaluated_at_tick", "required": true, "units": "ticks", "value_type": "unsigned-integer" }, { "description": "Origin site identity.", "id": "from_site_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Origin World X coordinate.", "id": "from_x_meters", "required": true, "units": "meters", "value_type": "number" }, { "description": "Origin World Y coordinate.", "id": "from_y_meters", "required": true, "units": "meters", "value_type": "number" }, { "description": "Unknown, discovered, current, or stale state.", "id": "knowledge", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Latest reported route pressure.", "id": "pressure", "required": false, "units": "pressure-units", "value_type": "signed-integer-or-null" }, { "description": "Containing route identity.", "id": "route_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Route-segment identity.", "id": "segment_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Destination site identity.", "id": "to_site_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Destination World X coordinate.", "id": "to_x_meters", "required": true, "units": "meters", "value_type": "number" }, { "description": "Destination World Y coordinate.", "id": "to_y_meters", "required": true, "units": "meters", "value_type": "number" } ], "id": "world.route.known", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "query", "name": "Known regional routes", "namespace": "world.route", "owner": "game.observer-knowledge and sim.world-topology", "replacement": null, "side_effects": "none", "signature": "world.route.known(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.route.known.html" }, { "authority": "read_only", "availability": "runtime API 1", "deprecated": null, "description": "Detached stable identities selected by presentation.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Namespace lookup is constant-time and performs no owner work.", "examples": [ "-- Access documented members through world.selection.current." ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "world.selection", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "world.selection.current" ], "returns": "A stable namespace table containing only the documented child symbols available to this package origin.", "signature": "namespace world.selection", "usage": "Use world.selection only to reach its registered child contracts. The namespace itself performs no query, mutation, lifecycle transition, or drawing." }, "errors": [], "fields": [], "id": "world.selection", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "namespace", "name": "Selection queries", "namespace": "world.selection", "owner": "render.selection", "replacement": null, "side_effects": "none", "signature": "namespace world.selection", "source_location": "src/app/script_api_catalog.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.selection.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns the stable identities selected by the presentation owner.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "Bounded by page size, per-package query budget, and the owning snapshot builder; results are detached before Lua receives them.", "examples": [ "local result = world.query(\"world.selection.current\", {page_size = 16})\nif result.status == \"completed\" then\n for _, record in ipairs(result.records) do\n -- Render or inspect detached record fields here.\n end\nend" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "world.selection.current", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [ "filters: optional table of query-specific stable IDs and bounded selectors.", "cursor: optional opaque continuation cursor returned by the same query.", "page_size: optional positive record limit capped by the host." ], "related": [ "world.selection", "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation", "world.query" ], "returns": "A detached query page with status, records, continuation metadata, and a stable diagnostic when the request cannot complete.", "signature": "world.selection.current(filters?, cursor?, page_size?) -> query-page", "usage": "Call this query through world.query with the stable ID world.selection.current. Consume detached records during the current callback and use the returned cursor for bounded continuation." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Selected stable entity identity.", "id": "entity_id", "required": true, "units": null, "value_type": "stable-id" } ], "id": "world.selection.current", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "query", "name": "Current selection", "namespace": "world.selection", "owner": "render.selection", "replacement": null, "side_effects": "none", "signature": "world.selection.current(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.selection.current.html" }, { "authority": "read_only", "availability": "runtime API 1", "deprecated": null, "description": "Detached current Settlement and supply facts.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Namespace lookup is constant-time and performs no owner work.", "examples": [ "-- Access documented members through world.settlement.capability." ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "world.settlement", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [], "related": [ "world.settlement.capability", "world.settlement.failure-pressure", "world.settlement.for-actor", "world.settlement.resources", "world.settlement.shortages" ], "returns": "A stable namespace table containing only the documented child symbols available to this package origin.", "signature": "namespace world.settlement", "usage": "Use world.settlement only to reach its registered child contracts. The namespace itself performs no query, mutation, lifecycle transition, or drawing." }, "errors": [], "fields": [], "id": "world.settlement", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "namespace", "name": "Settlement queries", "namespace": "world.settlement", "owner": "game.settlement", "replacement": null, "side_effects": "none", "signature": "namespace world.settlement", "source_location": "src/app/script_api_catalog.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.settlement.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns current membership, infrastructure, defense, and revision facts for one settlement.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "Bounded by page size, per-package query budget, and the owning snapshot builder; results are detached before Lua receives them.", "examples": [ "local result = world.query(\"world.settlement.capability\", {page_size = 16})\nif result.status == \"completed\" then\n for _, record in ipairs(result.records) do\n -- Render or inspect detached record fields here.\n end\nend" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "world.settlement.capability", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [ "filters: optional table of query-specific stable IDs and bounded selectors.", "cursor: optional opaque continuation cursor returned by the same query.", "page_size: optional positive record limit capped by the host." ], "related": [ "world.settlement", "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation", "world.query" ], "returns": "A detached query page with status, records, continuation metadata, and a stable diagnostic when the request cannot complete.", "signature": "world.settlement.capability(filters?, cursor?, page_size?) -> query-page", "usage": "Call this query through world.query with the stable ID world.settlement.capability. Consume detached records during the current callback and use the returned cursor for bounded continuation." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Member actor count.", "id": "actor_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Member building count.", "id": "building_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Member household count.", "id": "household_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Member job count.", "id": "job_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Owner revision.", "id": "revision", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Settlement identity.", "id": "settlement_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Member stockpile count.", "id": "stockpile_count", "required": true, "units": null, "value_type": "unsigned-integer" } ], "id": "world.settlement.capability", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "query", "name": "Settlement capability", "namespace": "world.settlement", "owner": "game.settlement", "replacement": null, "side_effects": "none", "signature": "world.settlement.capability(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.settlement.capability.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns one detached summary of current population viability, retained life-course transitions, authored bounds, and the current growth blockage.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "One exact retained Settlement strategy plus bounded Construction, Resource, Actor, Relationship, Household, Production, and Trade evidence; recurring demographic mutation remains limited by authored rotating visit and mutation budgets.", "examples": [ "local demography = world.query(\"world.settlement.demography\", {page_size = 1})" ], "history": [ "1.17.0: Authored recurring demography and current village viability summary added for Village Life addendum K.", "1.19.0: Retained population trajectory, cross-owner evidence, and explicit demographic gates added for civilization autonomy Q8." ], "id": "world.settlement.demography", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [ "cursor: optional continuation cursor.", "page_size: bounded summary-row limit." ], "related": [ "world.settlement.families", "world.settlement.life-events", "world.settlement.economy", "world.query" ], "returns": "One detached demographic row with the retained growing, stable, stagnating, declining, recovering, or abandoned trajectory; birth, immigration, and emigration decisions and reasons; current prosperity; population, labor, Household, housing, food, health, safety, service, enterprise, life-event, authored-limit, and visit-budget facts.", "signature": "world.settlement.demography(filters?, cursor?, page_size?) -> query-page", "usage": "Read the retained settlement population trajectory, demographic gates, current population, labor, household, housing, food, health, safety, service, enterprise, prosperity, and life-event evidence without changing the settlement." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Current active enterprise commitments.", "id": "active_enterprises", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Maximum Actors evaluated per demographic update.", "id": "actor_visit_budget", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Healthy adult share of residents.", "id": "adult_labor", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Healthy adult residents available to sustain labor.", "id": "adult_labor_population", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Whether current strategy permits the existing birth path.", "id": "birth_allowed", "required": true, "units": null, "value_type": "boolean" }, { "description": "Direct reason for the current birth gate.", "id": "birth_reason", "required": true, "units": null, "value_type": "string" }, { "description": "Retained Actor lineages created by birth.", "id": "births", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Retained growing, stable, stagnating, declining, recovering, or abandoned trajectory.", "id": "condition", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Actors with retained death facts.", "id": "deaths", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Actors with retained emigration facts.", "id": "emigrants", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Whether current strategy pressures an eligible resident to leave.", "id": "emigration_pressure", "required": true, "units": null, "value_type": "boolean" }, { "description": "Direct reason for the current emigration pressure.", "id": "emigration_reason", "required": true, "units": null, "value_type": "string" }, { "description": "Authored demographic evaluation cadence.", "id": "evaluation_interval_ticks", "required": true, "units": "ticks", "value_type": "unsigned-integer" }, { "description": "Accessible demographic food reserve.", "id": "food_units", "required": true, "units": "resource-units", "value_type": "unsigned-integer" }, { "description": "Current settlement-level reason growth cannot proceed.", "id": "growth_blockage", "required": false, "units": null, "value_type": "string-or-null" }, { "description": "Current resident health support.", "id": "health", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Current Settlement Households.", "id": "household_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Maximum Households evaluated per demographic update.", "id": "household_visit_budget", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Retained Household-owned separation formations.", "id": "households_separated", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Usable authored housing capacity.", "id": "housing_capacity", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Actors with retained immigration provenance.", "id": "immigrants", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Whether current strategy permits the existing immigration path.", "id": "immigration_allowed", "required": true, "units": null, "value_type": "boolean" }, { "description": "Authored ceiling for labor-driven immigration.", "id": "immigration_population_ceiling", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Direct reason for the current immigration gate.", "id": "immigration_reason", "required": true, "units": null, "value_type": "string" }, { "description": "Authored population level restored by recovery immigration.", "id": "immigration_recovery_population", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Authored population ceiling.", "id": "maximum_population", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Authored population floor.", "id": "minimum_population", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Maximum demographic mutations per update.", "id": "mutation_budget", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Retained Relationship-owned partnership formations.", "id": "partnerships_formed", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Current living Settlement residents.", "id": "population", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Whether population, housing, food, or Household strain creates decline pressure.", "id": "population_pressure", "required": true, "units": null, "value_type": "boolean" }, { "description": "Current prosperity evidence used by strategy.", "id": "prosperity", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Immigrants minus emigrants since the previous retained evaluation.", "id": "recent_migration_change", "required": true, "units": null, "value_type": "signed-integer" }, { "description": "Births minus deaths since the previous retained evaluation.", "id": "recent_natural_change", "required": true, "units": null, "value_type": "signed-integer" }, { "description": "Maximum Relationships evaluated per demographic update.", "id": "relationship_visit_budget", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Food required for the current resident count.", "id": "required_food_units", "required": true, "units": "resource-units", "value_type": "unsigned-integer" }, { "description": "Current settlement safety support.", "id": "safety", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Current selected enterprise opportunities.", "id": "selected_enterprises", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Current operational service support.", "id": "services", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Households above the authored demographic strain limit.", "id": "strained_households", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Authored sustainable target.", "id": "target_population", "required": true, "units": null, "value_type": "unsigned-integer" } ], "id": "world.settlement.demography", "introduced": { "display": "1.17.0", "major": 1, "minor": 17, "patch": 0 }, "kind": "query", "name": "Village demography", "namespace": "world.settlement", "owner": "assets.runtime-settlement-definition, game.actor-runtime, game.relationship, game.household, game.resource-economy, game.construction, and game.settlement", "replacement": null, "side_effects": "none", "signature": "world.settlement.demography(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.settlement.demography.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns one detached summary of the village's current production, pay, household market, and regional delivery state.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "One bounded Production order traversal, Trade shipment traversal, Resource container traversal, and custody-transfer traversal.", "examples": [ "local economy = world.query(\"world.settlement.economy\", {page_size = 1})" ], "history": [ "1.13.0: Live starter-village production, pay, household purchase, and merchant delivery summary added for Village Life addendum G.", "1.16.0: Authored opportunity keys, recurring cycle counts, generic output quantities, and current blockage explanations added for Village Life addendum J." ], "id": "world.settlement.economy", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [ "cursor: optional continuation cursor.", "page_size: bounded summary-row limit." ], "related": [ "world.settlement.resources", "world.settlement.families", "world.settlement.list", "world.query" ], "returns": "One detached economy row with authored opportunity keys, current stages and workers, completed cycle counts, known waits, wage and purchase completion, household output quantity, destination Site, and delivered trade quantity.", "signature": "world.settlement.economy(filters?, cursor?, page_size?) -> query-page", "usage": "Read the current authored production and trade opportunities, completed cycle counts, waits, pay, household purchase, merchant shipment, and delivered stock from their gameplay owners for the normal village interface." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Completed production cycles retained by Production.", "id": "completed_production_cycles", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Completed trade cycles retained by Trade.", "id": "completed_trade_cycles", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Authored trade resource held at its destination.", "id": "delivered_trade_quantity", "required": true, "units": "resource-units", "value_type": "unsigned-integer" }, { "description": "Current recipe output held by household goods inventories.", "id": "household_output_quantity", "required": true, "units": "resource-units", "value_type": "unsigned-integer" }, { "description": "Whether a household completed a goods purchase.", "id": "household_purchase_completed", "required": true, "units": null, "value_type": "boolean" }, { "description": "Merchant leading the shipment when present.", "id": "merchant_actor_id", "required": false, "units": null, "value_type": "stable-id-or-null" }, { "description": "Reason the current production cycle is waiting when known.", "id": "production_blockage", "required": false, "units": null, "value_type": "string-or-null" }, { "description": "Authored production opportunity being summarized.", "id": "production_opportunity_key", "required": false, "units": null, "value_type": "string-or-null" }, { "description": "Current production stage.", "id": "production_stage", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Assigned worker on the current production cycle when present.", "id": "production_worker_id", "required": false, "units": null, "value_type": "stable-id-or-null" }, { "description": "Reason the current trade cycle is waiting when known.", "id": "trade_blockage", "required": false, "units": null, "value_type": "string-or-null" }, { "description": "Shipment destination Site when present.", "id": "trade_destination_site_id", "required": false, "units": null, "value_type": "stable-id-or-null" }, { "description": "Authored trade opportunity being summarized.", "id": "trade_opportunity_key", "required": false, "units": null, "value_type": "string-or-null" }, { "description": "Current regional shipment stage.", "id": "trade_stage", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Whether a production wage was paid.", "id": "wage_paid", "required": true, "units": null, "value_type": "boolean" } ], "id": "world.settlement.economy", "introduced": { "display": "1.13.0", "major": 1, "minor": 13, "patch": 0 }, "kind": "query", "name": "Settlement economy", "namespace": "world.settlement", "owner": "game.production, game.trade, game.resource-economy, and game.household", "replacement": null, "side_effects": "none", "signature": "world.settlement.economy(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.settlement.economy.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns the latest Settlement-owned production and trade portfolio, direct viability evidence, selection, and authoritative commitment lifecycle.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "One exact Settlement lookup plus one bounded traversal of the latest retained enterprise portfolio. Recurring assessment, execution, reconciliation, and cancellation use authored cadence, visit, selection, and mutation budgets.", "examples": [ "local options = world.query(\"world.settlement.enterprise-options\", {filters = {settlement_id = 1}, page_size = 16})" ], "history": [ "1.19.0: Retained enterprise selection, authoritative Production and Trade bindings, reconsideration, and direct lifecycle evidence added for Phase 19Q7." ], "id": "world.settlement.enterprise-options", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [ "filters.settlement_id: required stable Settlement identity.", "cursor: optional continuation cursor over options in stable policy-key order.", "page_size: bounded option-row limit." ], "related": [ "world.settlement.production-options", "world.settlement.economy", "world.settlement.goals", "world.query" ], "returns": "Detached production and trade rows with current supply, demand, score, rejection, selection, and the exact Production order or Trade shipment identity, revision, and retained commitment lifecycle when bound.", "signature": "world.settlement.enterprise-options(filters?, cursor?, page_size?) -> query-page", "usage": "Inspect the Settlement-owned enterprise portfolio that selects and reconsiders real production and trade commitments. The query is detached and cannot create, advance, cancel, or replace a domain owner." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Available supply.", "id": "available_quantity", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Retained commitment lifecycle.", "id": "commitment_status", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Unsatisfied demand.", "id": "demand_quantity", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Direct selection, rejection, or lifecycle detail.", "id": "detail", "required": true, "units": null, "value_type": "string" }, { "description": "Fixed tick evaluated.", "id": "evaluation_tick", "required": true, "units": "fixed-ticks", "value_type": "unsigned-integer" }, { "description": "Production or trade commitment.", "id": "kind", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Bound domain owner.", "id": "owner_id", "required": false, "units": null, "value_type": "stable-id-or-null" }, { "description": "Production or Trade owner kind.", "id": "owner_kind", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Bound owner revision.", "id": "owner_revision", "required": false, "units": null, "value_type": "revision-or-null" }, { "description": "Authored enterprise opportunity identity.", "id": "policy_key", "required": true, "units": null, "value_type": "string" }, { "description": "Direct rejection or none.", "id": "rejection", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Required supply.", "id": "required_quantity", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Primary resource identity.", "id": "resource_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Deterministic score.", "id": "score", "required": true, "units": "basis-points", "value_type": "signed-integer" }, { "description": "Whether Settlement selected this commitment.", "id": "selected", "required": true, "units": null, "value_type": "boolean" }, { "description": "Settlement identity.", "id": "settlement_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Current Settlement revision.", "id": "settlement_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Revision evaluated.", "id": "source_settlement_revision", "required": true, "units": null, "value_type": "revision" } ], "id": "world.settlement.enterprise-options", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "query", "name": "Settlement enterprise options", "namespace": "world.settlement", "owner": "game.settlement", "replacement": null, "side_effects": "none", "signature": "world.settlement.enterprise-options(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.settlement.enterprise-options.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns current settlement-region weather, ecology, and the resulting routine adaptation.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "One bounded Environment region traversal, Ecology population and renewable-source traversal, and Household traversal.", "examples": [ "local conditions = world.query(\"world.settlement.environment\", {page_size = 1})" ], "history": [ "1.14.0: Weather and regional ecology now explain routine sheltering and resource conservation for Village Life addendum H.", "1.15.0: Hazardous weather now records bounded Household disruption and safe-weather recovery for Village Life addendum I." ], "id": "world.settlement.environment", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [ "cursor: optional continuation cursor.", "page_size: bounded summary-row limit." ], "related": [ "world.calendar.current", "world.actor.routine", "world.settlement.resources", "world.query" ], "returns": "One detached row with region, biome, weather, pressure, resident adaptation, outdoor-work availability, wildlife populations, renewable availability, and stable, disrupted, or recovering household counts.", "signature": "world.settlement.environment(filters?, cursor?, page_size?) -> query-page", "usage": "Read the starter settlement region's current weather, ecology, resulting resident adaptation, and retained household disruption without changing owner state." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Current resident routine adaptation.", "id": "adaptation", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Settlement region biome.", "id": "biome", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Households retaining environmental strain.", "id": "disrupted_households", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Environmental strain retained across all households.", "id": "environmental_household_strain", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Current combined biome, season, and weather pressure.", "id": "environmental_pressure", "required": true, "units": "pressure-units", "value_type": "signed-integer" }, { "description": "Current regional grazer population.", "id": "grazer_population", "required": true, "units": "population-units", "value_type": "unsigned-integer" }, { "description": "Current stable, disrupted, or recovering household condition.", "id": "household_condition", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Whether current conditions permit new outdoor work.", "id": "outdoor_work_available", "required": true, "units": null, "value_type": "boolean" }, { "description": "Current regional predator population.", "id": "predator_population", "required": true, "units": "population-units", "value_type": "unsigned-integer" }, { "description": "Households in the bounded safe-weather recovery window.", "id": "recovering_households", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Settlement region identity.", "id": "region_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Available renewable resources in the region.", "id": "renewable_available", "required": true, "units": "resource-units", "value_type": "unsigned-integer" }, { "description": "Renewable resource capacity in the region.", "id": "renewable_capacity", "required": true, "units": "resource-units", "value_type": "unsigned-integer" }, { "description": "Current settlement weather.", "id": "weather", "required": true, "units": null, "value_type": "enumeration" } ], "id": "world.settlement.environment", "introduced": { "display": "1.14.0", "major": 1, "minor": 14, "patch": 0 }, "kind": "query", "name": "Settlement environment", "namespace": "world.settlement", "owner": "sim.world-environment, sim.world-ecology, game.actor-routine, and game.household", "replacement": null, "side_effects": "none", "signature": "world.settlement.environment(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.settlement.environment.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns defense severity and maintenance pressure for one settlement.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "Bounded by page size, per-package query budget, and the owning snapshot builder; results are detached before Lua receives them.", "examples": [ "local result = world.query(\"world.settlement.failure-pressure\", {page_size = 16})\nif result.status == \"completed\" then\n for _, record in ipairs(result.records) do\n -- Render or inspect detached record fields here.\n end\nend" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "world.settlement.failure-pressure", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [ "filters: optional table of query-specific stable IDs and bounded selectors.", "cursor: optional opaque continuation cursor returned by the same query.", "page_size: optional positive record limit capped by the host." ], "related": [ "world.settlement", "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation", "world.query" ], "returns": "A detached query page with status, records, continuation metadata, and a stable diagnostic when the request cannot complete.", "signature": "world.settlement.failure-pressure(filters?, cursor?, page_size?) -> query-page", "usage": "Call this query through world.query with the stable ID world.settlement.failure-pressure. Consume detached records during the current callback and use the returned cursor for bounded continuation." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Whether settlement defense is alarmed.", "id": "alarmed", "required": true, "units": null, "value_type": "boolean" }, { "description": "Current defense pressure.", "id": "defense_severity", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Building maintenance threshold.", "id": "maintenance_threshold", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Settlement identity.", "id": "settlement_id", "required": true, "units": null, "value_type": "stable-id" } ], "id": "world.settlement.failure-pressure", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "query", "name": "Settlement failure pressure", "namespace": "world.settlement", "owner": "game.settlement", "replacement": null, "side_effects": "none", "signature": "world.settlement.failure-pressure(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.settlement.failure-pressure.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns current Household membership, life-stage counts, residence, and latest change together with physical pantry and domestic-work facts.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "One Settlement lookup, one bounded Household lookup per row, one Actor lookup per retained member, one pantry traversal, and one bounded Supply traversal per Household.", "examples": [ "local families = world.query(\"world.settlement.families\", {page_size = 8})" ], "history": [ "1.11.0: Current family and life-stage summary added for Village Life addendum E.", "1.12.0: Physical pantry, Household strain, latest care, and domestic Work facts added for Village Life addendum F.", "1.19.3: Adolescent Household counts added for Village Life O2." ], "id": "world.settlement.families", "manual_nodes": [ "phase.17", "phase.19", "engine-reference.extension-contract" ], "parameters": [ "cursor: optional continuation cursor.", "page_size: bounded household-row limit." ], "related": [ "world.settlement.life-events", "world.household.for-actor", "world.settlement.list", "world.query" ], "returns": "Detached Household rows in current Settlement order with child, adolescent, adult, elder, residence, pantry food, strain, latest care, latest domestic Work, reason, and update facts.", "signature": "world.settlement.families(filters?, cursor?, page_size?) -> query-page", "usage": "Read current village households, their membership and life-stage counts, assigned residence, physical pantry reserve, strain, latest care, and latest domestic Work without changing family state." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Current adolescent members.", "id": "adolescent_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Current adult members.", "id": "adult_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Current child members.", "id": "child_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Latest pantry-restocking Work stage.", "id": "domestic_work_stage", "required": false, "units": null, "value_type": "enumeration-or-null" }, { "description": "Actor assigned to the latest pantry-restocking Work.", "id": "domestic_worker_id", "required": false, "units": null, "value_type": "stable-id-or-null" }, { "description": "Current elder members.", "id": "elder_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Household identity.", "id": "household_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Latest Household change reason.", "id": "last_reason", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Latest retained care activity.", "id": "latest_care_kind", "required": false, "units": null, "value_type": "enumeration-or-null" }, { "description": "Tick of the latest retained care activity.", "id": "latest_care_tick", "required": false, "units": "ticks", "value_type": "unsigned-integer-or-null" }, { "description": "Current Household members.", "id": "member_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Food units physically held by the Household pantry.", "id": "pantry_food_quantity", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Assigned residence.", "id": "residence_building_id", "required": false, "units": null, "value_type": "stable-id-or-null" }, { "description": "Current Household strain.", "id": "strain", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Latest Household update.", "id": "updated_at_tick", "required": true, "units": "ticks", "value_type": "unsigned-integer" } ], "id": "world.settlement.families", "introduced": { "display": "1.11.0", "major": 1, "minor": 11, "patch": 0 }, "kind": "query", "name": "Village families", "namespace": "world.settlement", "owner": "game.household, game.actor-runtime, game.resource-economy, game.settlement-supply, and game.settlement", "replacement": null, "side_effects": "none", "signature": "world.settlement.families(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.settlement.families.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns capability facts for the settlement that contains one actor.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "Bounded by page size, per-package query budget, and the owning snapshot builder; results are detached before Lua receives them.", "examples": [ "local result = world.query(\"world.settlement.for-actor\", {page_size = 16})\nif result.status == \"completed\" then\n for _, record in ipairs(result.records) do\n -- Render or inspect detached record fields here.\n end\nend" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "world.settlement.for-actor", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [ "filters: optional table of query-specific stable IDs and bounded selectors.", "cursor: optional opaque continuation cursor returned by the same query.", "page_size: optional positive record limit capped by the host." ], "related": [ "world.settlement", "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation", "world.query" ], "returns": "A detached query page with status, records, continuation metadata, and a stable diagnostic when the request cannot complete.", "signature": "world.settlement.for-actor(filters?, cursor?, page_size?) -> query-page", "usage": "Call this query through world.query with the stable ID world.settlement.for-actor. Consume detached records during the current callback and use the returned cursor for bounded continuation." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Member actor count.", "id": "actor_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Member building count.", "id": "building_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Member household count.", "id": "household_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Member job count.", "id": "job_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Owner revision.", "id": "revision", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Settlement identity.", "id": "settlement_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Member stockpile count.", "id": "stockpile_count", "required": true, "units": null, "value_type": "unsigned-integer" } ], "id": "world.settlement.for-actor", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "query", "name": "Settlement for actor", "namespace": "world.settlement", "owner": "game.settlement", "replacement": null, "side_effects": "none", "signature": "world.settlement.for-actor(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.settlement.for-actor.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns the latest Settlement-owned goal portfolio, including committed goals and rejected or deferred alternatives.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "One exact Settlement lookup plus one bounded traversal of the latest retained goal-candidate page. Recurring evaluation uses the settlement definition's rotating visit budget and fixed cadence.", "examples": [ "local goals = world.query(\"world.settlement.goals\", {filters = {settlement_id = 1}, page_size = 16})" ], "history": [ "1.19.0: Durable concurrent settlement goals, sponsors, dependencies, reconsideration, and rejected alternatives added for Phase 19Q2." ], "id": "world.settlement.goals", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [ "filters.settlement_id: required stable Settlement identity.", "cursor: optional continuation cursor over candidates in stable goal-key order.", "page_size: bounded candidate-row limit." ], "related": [ "world.settlement.needs", "world.project.proposals", "world.settlement.list", "world.query" ], "returns": "Detached candidate rows with stable goal identity when retained, source and sponsor kinds, need domain, source strength, weighted score, benefit, cost, risk, opportunity cost, reconsideration threshold, dependency and incompatibility counts, status, eligibility, selection, and direct decision detail.", "signature": "world.settlement.goals(filters?, cursor?, page_size?) -> query-page", "usage": "Read the latest Settlement-owned portfolio of committed, paused, retired, and rejected civic goals without creating work or mutating any owner. Supply settlement_id to select the settlement." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Durable portfolio sequence count.", "id": "completed_evaluation_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Declared prerequisite goal count.", "id": "dependency_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Direct selection or rejection reason.", "id": "detail", "required": true, "units": null, "value_type": "string" }, { "description": "Typed settlement need domain.", "id": "domain", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Whether the candidate passed source and score gates.", "id": "eligible", "required": true, "units": null, "value_type": "boolean" }, { "description": "Fixed tick evaluated.", "id": "evaluation_tick", "required": true, "units": "fixed-ticks", "value_type": "unsigned-integer" }, { "description": "Expected benefit.", "id": "expected_benefit", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Expected cost.", "id": "expected_cost", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Durable goal identity when one exists.", "id": "goal_id", "required": false, "units": null, "value_type": "stable-id-or-null" }, { "description": "Data-authored goal identity.", "id": "goal_key", "required": true, "units": null, "value_type": "string" }, { "description": "Declared incompatible goal count.", "id": "incompatibility_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Next fixed tick when evaluation may run.", "id": "next_evaluation_tick", "required": true, "units": "fixed-ticks", "value_type": "unsigned-integer" }, { "description": "Opportunity cost.", "id": "opportunity_cost", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Weighted portfolio score.", "id": "priority_score", "required": true, "units": "basis-points", "value_type": "signed-integer" }, { "description": "Source threshold below which a retained goal retires.", "id": "reconsider_below", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Expected risk.", "id": "risk", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Whether the portfolio committed the candidate.", "id": "selected", "required": true, "units": null, "value_type": "boolean" }, { "description": "Settlement identity.", "id": "settlement_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Current Settlement owner revision.", "id": "settlement_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Need, opportunity, obligation, or ambition.", "id": "source_kind", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Need assessment used as source evidence.", "id": "source_need_assessment_tick", "required": true, "units": "fixed-ticks", "value_type": "unsigned-integer" }, { "description": "Settlement revision used to evaluate the portfolio.", "id": "source_settlement_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Current source strength.", "id": "source_strength", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Stable sponsor identity.", "id": "sponsor_id", "required": true, "units": null, "value_type": "string" }, { "description": "Household, business, civic, or institution.", "id": "sponsor_kind", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Committed, paused, retired, or rejected.", "id": "status", "required": true, "units": null, "value_type": "enumeration" } ], "id": "world.settlement.goals", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "query", "name": "Settlement goals", "namespace": "world.settlement", "owner": "game.settlement", "replacement": null, "side_effects": "none", "signature": "world.settlement.goals(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.settlement.goals.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns the bounded Settlement-owned lifecycle that binds a selected housing method to its Household and authoritative Construction or completed Building outcome.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "One exact Settlement lookup plus one bounded traversal of the retained execution ledger in stable identity order. Runtime starts and reconciliation use separate authored visit and mutation budgets.", "examples": [ "local executions = world.query(\"world.settlement.housing-executions\", {filters = {settlement_id = 1}, page_size = 16})\nfor _, execution in ipairs(executions.records) do\n ui.text(execution.method, execution.status .. \": \" .. execution.detail)\nend" ], "history": [ "1.19.0: Durable housing execution bindings, blockers, and authoritative outcomes added for Phase 19Q5D." ], "id": "world.settlement.housing-executions", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [ "filters.settlement_id: required stable Settlement identity.", "filters.household_id: optional stable Household identity.", "cursor: optional continuation cursor over stable execution identities.", "page_size: bounded execution-row limit." ], "related": [ "world.settlement.housing-parcels", "world.settlement.housing-methods", "world.construction.progress", "world.query" ], "returns": "Detached execution rows with stable identity, selected method and optional parcel keys, Household, method, target Building, building definition, Construction, resulting Building, lifecycle, source evaluation ticks, source Household revision, latest owner revision, explanation, and creation and update ticks.", "signature": "world.settlement.housing-executions(filters?, cursor?, page_size?) -> query-page", "usage": "Inspect the bounded Settlement-owned lifecycle that binds a selected housing method to one Household and the authoritative Construction or completed Building outcome. Supply settlement_id and optionally household_id. The query cannot start, advance, cancel, or mutate housing work." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Building definition used.", "id": "building_definition_id", "required": true, "units": null, "value_type": "string" }, { "description": "Bound Construction identity.", "id": "construction_id", "required": false, "units": null, "value_type": "stable-id-or-null" }, { "description": "Execution creation tick.", "id": "created_at_tick", "required": true, "units": "fixed-ticks", "value_type": "unsigned-integer" }, { "description": "Direct lifecycle or blocker explanation.", "id": "detail", "required": true, "units": null, "value_type": "string" }, { "description": "Durable housing execution identity.", "id": "execution_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Destination Household identity.", "id": "household_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Selected housing method.", "id": "method", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Selected housing-method identity.", "id": "method_option_key", "required": true, "units": null, "value_type": "string" }, { "description": "Latest authoritative outcome revision.", "id": "owner_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Selected parcel identity.", "id": "parcel_option_key", "required": false, "units": null, "value_type": "string-or-null" }, { "description": "Completed Building identity.", "id": "resulting_building_id", "required": false, "units": null, "value_type": "stable-id-or-null" }, { "description": "Settlement identity.", "id": "settlement_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Current Settlement owner revision.", "id": "settlement_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Household revision selected.", "id": "source_household_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Housing-method evaluation used.", "id": "source_method_evaluation_tick", "required": true, "units": "fixed-ticks", "value_type": "unsigned-integer" }, { "description": "Parcel evaluation used, or zero for methods without parcels.", "id": "source_parcel_evaluation_tick", "required": true, "units": "fixed-ticks", "value_type": "unsigned-integer" }, { "description": "Active, completed, blocked, cancelled, or failed.", "id": "status", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Existing target Building.", "id": "target_building_id", "required": false, "units": null, "value_type": "stable-id-or-null" }, { "description": "Latest lifecycle update tick.", "id": "updated_at_tick", "required": true, "units": "fixed-ticks", "value_type": "unsigned-integer" } ], "id": "world.settlement.housing-executions", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "query", "name": "Settlement housing executions", "namespace": "world.settlement", "owner": "game.settlement", "replacement": null, "side_effects": "none", "signature": "world.settlement.housing-executions(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.settlement.housing-executions.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns Settlement-owned repair, extension, shared-residence, and new-construction options from the latest current facts, including feasibility, score, selection, cost, capacity, evidence revisions, and direct rejection reason.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "One exact Settlement lookup plus one bounded traversal of the current retained method ledger. Recurring comparison uses data-authored rotating Household and candidate visit budgets.", "examples": [ "local methods = world.query(\"world.settlement.housing-methods\", {filters = {settlement_id = 1}, page_size = 16})\nfor _, option in ipairs(methods.records) do\n ui.text(option.method, option.detail)\nend" ], "history": [ "1.19.0: Bounded housing-method alternatives, current feasibility evidence, stable selection, and direct rejection reasons added for Phase 19Q5B." ], "id": "world.settlement.housing-methods", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [ "filters.settlement_id: required stable Settlement identity.", "filters.household_id: optional stable Household identity.", "cursor: optional continuation cursor over stable option identities.", "page_size: bounded option-row limit." ], "related": [ "world.settlement.housing-pressure", "world.settlement.needs", "world.household.wealth", "world.query" ], "returns": "Detached option rows with method and policy identity, target Building or definition, pressure, capacity gain or deficit, condition recovery, compatibility, materials, labor, access, wealth, benefit, cost, risk, score, selection or direct rejection, and exact source revisions.", "signature": "world.settlement.housing-methods(filters?, cursor?, page_size?) -> query-page", "usage": "Inspect the Settlement-owned repair, extension, shared-residence, and new-construction alternatives composed from current Household, Building, Resource, Work, Relationship, and World facts. Supply settlement_id and optionally household_id. The query cannot select a parcel or start work." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Current route cost.", "id": "access_cost_ticks", "required": true, "units": "fixed-ticks", "value_type": "unsigned-integer" }, { "description": "Available required units.", "id": "available_material_units", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Weighted benefit.", "id": "benefit", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Target building definition.", "id": "building_definition_id", "required": true, "units": null, "value_type": "string" }, { "description": "Target Building revision.", "id": "building_revision", "required": false, "units": null, "value_type": "revision-or-null" }, { "description": "Unmet capacity.", "id": "capacity_deficit", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Capacity this method could add.", "id": "capacity_gain", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Shared-residence social compatibility.", "id": "compatibility", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Condition this method could restore.", "id": "condition_recovery", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Weighted scarcity cost.", "id": "cost", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Direct selection or rejection explanation.", "id": "detail", "required": true, "units": null, "value_type": "string" }, { "description": "Available adult workers.", "id": "eligible_labor_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Household considering the method.", "id": "household_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Household revision assessed.", "id": "household_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Current household wealth.", "id": "household_wealth", "required": true, "units": "minor-currency-units", "value_type": "unsigned-integer" }, { "description": "Material stockpile.", "id": "material_source_id", "required": false, "units": null, "value_type": "stable-id-or-null" }, { "description": "Repair, extension, shared residence, or new construction.", "id": "method", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Stable option identity.", "id": "option_key", "required": true, "units": null, "value_type": "string" }, { "description": "Data-authored method policy identity.", "id": "policy_key", "required": true, "units": null, "value_type": "string" }, { "description": "Current housing pressure.", "id": "pressure", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Direct feasibility or portfolio result.", "id": "rejection", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Required material units.", "id": "required_material_units", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Required labor units.", "id": "required_work_units", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Resource evidence revision.", "id": "resource_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Authored method risk.", "id": "risk", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Weighted method score.", "id": "score", "required": true, "units": "basis-points", "value_type": "signed-integer" }, { "description": "Whether this is the selected method.", "id": "selected", "required": true, "units": null, "value_type": "boolean" }, { "description": "Settlement identity.", "id": "settlement_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Current Settlement owner revision.", "id": "settlement_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Housing pressure evidence tick.", "id": "source_pressure_tick", "required": true, "units": "fixed-ticks", "value_type": "unsigned-integer" }, { "description": "Settlement revision assessed.", "id": "source_settlement_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Existing target Building.", "id": "target_building_id", "required": false, "units": null, "value_type": "stable-id-or-null" }, { "description": "Method wealth cost.", "id": "wealth_cost", "required": true, "units": "minor-currency-units", "value_type": "unsigned-integer" }, { "description": "Work evidence revision.", "id": "work_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "World evidence revision.", "id": "world_revision", "required": true, "units": null, "value_type": "revision" } ], "id": "world.settlement.housing-methods", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "query", "name": "Household housing methods", "namespace": "world.settlement", "owner": "game.settlement", "replacement": null, "side_effects": "none", "signature": "world.settlement.housing-methods(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.settlement.housing-methods.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns Settlement-owned physically feasible new-housing parcel alternatives from the latest selected new-construction method, including the exact composite key, placement, source revisions, score components, selection, and rejection reason.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "One exact Settlement lookup plus one bounded traversal of the current retained parcel ledger. Recurring comparison uses the settlement definition's World candidate and proximity-cell visit budgets.", "examples": [ "local parcels = world.query(\"world.settlement.housing-parcels\", {filters = {settlement_id = 1}, page_size = 16})\nfor _, parcel in ipairs(parcels.records) do\n ui.text(parcel.option_key, parcel.rejection .. \": \" .. parcel.detail)\nend" ], "history": [ "1.19.0: Bounded World parcel alternatives, complete spatial evidence, stable settlement-wide selection, and direct rejection reasons added for Phase 19Q5C2B." ], "id": "world.settlement.housing-parcels", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [ "filters.settlement_id: required stable Settlement identity.", "filters.household_id: optional stable Household identity associated with the selected construction method.", "cursor: optional continuation cursor over stable composite parcel identities.", "page_size: bounded parcel-row limit." ], "related": [ "world.settlement.housing-methods", "world.settlement.housing-pressure", "world.construction.active", "world.query" ], "returns": "Detached parcel rows with composite identity, source method, Household and building definition, area, origin, rotation variant, footprint and access evidence, source revisions, pressure, service, neighboring-land, material, labor, travel, control, risk, total score, selection or direct rejection, and explanation.", "signature": "world.settlement.housing-parcels(filters?, cursor?, page_size?) -> query-page", "usage": "Inspect the Settlement-owned comparison of complete World parcel alternatives for the currently selected new-construction housing method. Supply settlement_id and optionally household_id. The query cannot reserve land, create construction work, or mutate any gameplay owner." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Exact path distance.", "id": "access_distance", "required": true, "units": "millimeters", "value_type": "unsigned-integer" }, { "description": "Exact path travel cost.", "id": "access_travel_ticks", "required": true, "units": "fixed-ticks", "value_type": "unsigned-integer" }, { "description": "Reachable perimeter access x.", "id": "access_x", "required": true, "units": "world-cells", "value_type": "signed-integer" }, { "description": "Reachable perimeter access y.", "id": "access_y", "required": true, "units": "world-cells", "value_type": "signed-integer" }, { "description": "World land-area identity.", "id": "area_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "World land-area revision.", "id": "area_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Building definition to place.", "id": "building_definition_id", "required": true, "units": null, "value_type": "string" }, { "description": "Current Site control certainty.", "id": "control_certainty", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Direct selection or rejection explanation.", "id": "detail", "required": true, "units": null, "value_type": "string" }, { "description": "Exact occupied-cell count.", "id": "footprint_cell_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Pre-rotated footprint identity.", "id": "footprint_variant_id", "required": true, "units": null, "value_type": "string" }, { "description": "Household requiring the new residence.", "id": "household_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Household revision assessed.", "id": "household_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "World infrastructure revision.", "id": "infrastructure_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Labor readiness.", "id": "labor_readiness", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Material readiness.", "id": "material_readiness", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Selected housing-method source identity.", "id": "method_option_key", "required": true, "units": null, "value_type": "string" }, { "description": "Selected housing-method score.", "id": "method_score", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "World navigation revision.", "id": "navigation_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Compatible neighboring settlement land.", "id": "neighboring_land_use", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Stable composite parcel option identity.", "id": "option_key", "required": true, "units": null, "value_type": "string" }, { "description": "Exact footprint origin x.", "id": "origin_x", "required": true, "units": "world-cells", "value_type": "signed-integer" }, { "description": "Exact footprint origin y.", "id": "origin_y", "required": true, "units": "world-cells", "value_type": "signed-integer" }, { "description": "Data-authored housing policy identity.", "id": "policy_key", "required": true, "units": null, "value_type": "string" }, { "description": "Current housing pressure.", "id": "pressure", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Direct policy or portfolio result.", "id": "rejection", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Resource revision assessed.", "id": "resource_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Housing-method risk.", "id": "risk", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Weighted parcel score.", "id": "score", "required": true, "units": "basis-points", "value_type": "signed-integer" }, { "description": "Whether this is the selected settlement parcel.", "id": "selected", "required": true, "units": null, "value_type": "boolean" }, { "description": "Nearby road-service access.", "id": "service_access", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Settlement identity.", "id": "settlement_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Current Settlement owner revision.", "id": "settlement_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Housing-method evaluation used.", "id": "source_method_evaluation_tick", "required": true, "units": "fixed-ticks", "value_type": "unsigned-integer" }, { "description": "Settlement revision assessed.", "id": "source_settlement_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Inverse travel cost.", "id": "travel_efficiency", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Work revision assessed.", "id": "work_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Combined World evidence revision.", "id": "world_revision", "required": true, "units": null, "value_type": "revision" } ], "id": "world.settlement.housing-parcels", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "query", "name": "Settlement housing parcels", "namespace": "world.settlement", "owner": "game.settlement", "replacement": null, "side_effects": "none", "signature": "world.settlement.housing-parcels(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.settlement.housing-parcels.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns the latest Settlement-owned housing pressure for each assessed household, including current and forecast capacity, condition, privacy, access, wealth, owner revisions, and direct reason.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "One exact Settlement lookup plus one bounded traversal of the latest retained housing assessment. Recurring assessment uses the data-authored rotating Household visit budget and normal need cadence.", "examples": [ "local housing = world.query(\"world.settlement.housing-pressure\", {filters = {settlement_id = 1}, page_size = 16})\nfor _, household in ipairs(housing.records) do\n ui.text(tostring(household.household_id), household.status .. \": \" .. household.reason)\nend" ], "history": [ "1.19.0: Household-specific current and forecast housing pressure, causal components, and owner revision evidence added for Phase 19Q5A." ], "id": "world.settlement.housing-pressure", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [ "filters.settlement_id: required stable Settlement identity.", "filters.household_id: optional stable Household identity.", "cursor: optional continuation cursor over households in stable identity order.", "page_size: bounded household-row limit." ], "related": [ "world.settlement.needs", "world.settlement.families", "world.settlement.demography", "world.household.wealth", "world.query" ], "returns": "Detached Household rows with current and forecast membership, residence, capacity, occupancy, sharing, condition, privacy, route access, wealth, six causal pressure components, weighted severity, status, confidence, direct reason, assessment cadence, and exact source-owner revisions.", "signature": "world.settlement.housing-pressure(filters?, cursor?, page_size?) -> query-page", "usage": "Read the latest Settlement-owned housing pressure for every assessed Household without selecting a repair, extension, shared residence, new building, or parcel. Supply settlement_id and optionally household_id to narrow the detached page." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Route cost between settlement anchor and residence.", "id": "access_cost_ticks", "required": true, "units": "fixed-ticks", "value_type": "unsigned-integer" }, { "description": "Route access pressure.", "id": "access_pressure", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Whether the residence route is reachable.", "id": "access_reachable", "required": true, "units": null, "value_type": "boolean" }, { "description": "Highest Actor revision assessed.", "id": "actor_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Household evidence tick.", "id": "assessed_at_tick", "required": true, "units": "fixed-ticks", "value_type": "unsigned-integer" }, { "description": "Fixed tick assessed.", "id": "assessment_tick", "required": true, "units": "fixed-ticks", "value_type": "unsigned-integer" }, { "description": "Residence condition.", "id": "building_condition", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Residence revision assessed.", "id": "building_revision", "required": false, "units": null, "value_type": "revision-or-null" }, { "description": "Durable settlement assessment sequence count.", "id": "completed_assessment_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Building-condition pressure.", "id": "condition_pressure", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Assessment confidence.", "id": "confidence", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Capacity shortfall pressure.", "id": "crowding_pressure", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Current dependent members.", "id": "current_dependents", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Current Household members.", "id": "current_members", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Forecast-dependent pressure.", "id": "dependent_pressure", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Additional dependents included in the housing forecast.", "id": "expected_dependents", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Assessed Household identity.", "id": "household_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Household revision assessed.", "id": "household_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Current household currency balance.", "id": "household_wealth", "required": true, "units": "minor-currency-units", "value_type": "unsigned-integer" }, { "description": "Next fixed tick when housing pressure may be reassessed.", "id": "next_assessment_tick", "required": true, "units": "fixed-ticks", "value_type": "unsigned-integer" }, { "description": "Current household privacy.", "id": "privacy", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Shared-residence privacy pressure.", "id": "privacy_pressure", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Direct strongest housing-pressure reason.", "id": "reason", "required": true, "units": null, "value_type": "string" }, { "description": "Highest Relationship revision assessed.", "id": "relationship_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Private capacity required by current and forecast members.", "id": "required_capacity", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Current residence Building identity.", "id": "residence_building_id", "required": false, "units": null, "value_type": "stable-id-or-null" }, { "description": "Current residence capacity.", "id": "residence_capacity", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "All current occupants of the residence.", "id": "residence_occupants", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Highest Resource revision assessed.", "id": "resource_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Settlement identity.", "id": "settlement_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Current Settlement owner revision.", "id": "settlement_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Weighted housing-pressure severity.", "id": "severity", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Households sharing the current residence.", "id": "sharing_households", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Settlement revision used to compose the assessment.", "id": "source_settlement_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Adequate, strained, or critical pressure.", "id": "status", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Improving, stable, or worsening pressure.", "id": "trend", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Household reserve pressure.", "id": "wealth_pressure", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Configured household wealth reserve.", "id": "wealth_target", "required": true, "units": "minor-currency-units", "value_type": "unsigned-integer" }, { "description": "World revision assessed.", "id": "world_revision", "required": true, "units": null, "value_type": "revision" } ], "id": "world.settlement.housing-pressure", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "query", "name": "Household housing pressure", "namespace": "world.settlement", "owner": "game.settlement", "replacement": null, "side_effects": "none", "signature": "world.settlement.housing-pressure(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.settlement.housing-pressure.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns newest-first partnership, separation, birth, immigration, emigration, and death facts derived from their authoritative owners.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "One bounded Household, Relationship, and Actor traversal plus indexed Settlement, Resource wallet, and display-name lookups.", "examples": [ "local events = world.query(\"world.settlement.life-events\", {page_size = 3})" ], "history": [ "1.11.0: Family formation and population life events added for Village Life addendum E." ], "id": "world.settlement.life-events", "manual_nodes": [ "phase.17", "phase.19", "engine-reference.extension-contract" ], "parameters": [ "cursor: optional continuation cursor.", "page_size: bounded life-event row limit." ], "related": [ "world.settlement.families", "world.actor.status", "world.settlement.list", "world.query" ], "returns": "Newest-first detached life-event rows with the event kind, tick, primary Actor, optional related Actor and Household, and a direct summary.", "signature": "world.settlement.life-events(filters?, cursor?, page_size?) -> query-page", "usage": "Read retained partnership, birth, immigration, emigration, and death facts from their current gameplay owners for the normal village interface." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Primary Actor display name.", "id": "actor_display_name", "required": true, "units": null, "value_type": "string" }, { "description": "Primary Actor identity.", "id": "actor_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Direct player-facing event summary.", "id": "detail", "required": true, "units": null, "value_type": "string" }, { "description": "Related Household when present.", "id": "household_id", "required": false, "units": null, "value_type": "stable-id-or-null" }, { "description": "Partnership, separation, birth, immigration, emigration, or death.", "id": "kind", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Retained event tick.", "id": "occurred_at_tick", "required": true, "units": "ticks", "value_type": "unsigned-integer" }, { "description": "Related Actor when present.", "id": "related_actor_id", "required": false, "units": null, "value_type": "stable-id-or-null" } ], "id": "world.settlement.life-events", "introduced": { "display": "1.11.0", "major": 1, "minor": 11, "patch": 0 }, "kind": "query", "name": "Village life events", "namespace": "world.settlement", "owner": "game.actor-runtime, game.relationship, game.household, game.settlement, and game.resource-economy", "replacement": null, "side_effects": "none", "signature": "world.settlement.life-events(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.settlement.life-events.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns a bounded stable-ID page of loaded Settlement capability facts.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "Bounded by page size and direct Settlement index visits.", "examples": [ "local villages = world.query(\"world.settlement.list\", {page_size = 1})" ], "history": [ "1.9.0: Bounded settlement listing added for the normal village interface." ], "id": "world.settlement.list", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [ "cursor: optional continuation cursor.", "page_size: bounded settlement count." ], "related": [ "world.settlement", "world.settlement.for-actor", "world.construction.active" ], "returns": "Detached Settlement identities, revisions, names, and resident, Household, Building, stockpile, and active-project counts in stable order.", "signature": "world.settlement.list(filters?, cursor?, page_size?) -> query-page", "usage": "Read a bounded stable page of loaded settlements without requiring an Actor selection. Use the detached counts for the normal village summary." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Member actor count.", "id": "actor_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Member building count.", "id": "building_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Member household count.", "id": "household_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Member job count.", "id": "job_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Owner revision.", "id": "revision", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Settlement identity.", "id": "settlement_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Member stockpile count.", "id": "stockpile_count", "required": true, "units": null, "value_type": "unsigned-integer" } ], "id": "world.settlement.list", "introduced": { "display": "1.9.0", "major": 1, "minor": 9, "patch": 0 }, "kind": "query", "name": "Loaded settlements", "namespace": "world.settlement", "owner": "game.settlement", "replacement": null, "side_effects": "none", "signature": "world.settlement.list(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.settlement.list.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns the latest retained settlement needs, forecasts, severity, evidence count, and direct reason for one settlement.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "One exact Settlement lookup plus one bounded traversal of the latest retained need assessment page. Recurring assessment uses the settlement definition's rotating visit budget and fixed cadence.", "examples": [ "local needs = world.query(\"world.settlement.needs\", {filters = {settlement_id = 1}, page_size = 8})" ], "history": [ "1.19.0: Settlement-owned dynamic need forecasts and causal evidence added for Phase 19Q1." ], "id": "world.settlement.needs", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [ "filters.settlement_id: required stable Settlement identity.", "cursor: optional continuation cursor over needs in stable domain order.", "page_size: bounded need-row limit." ], "related": [ "world.settlement.list", "world.settlement.resources", "world.settlement.demography", "world.query" ], "returns": "Detached need rows with the current and source Settlement revisions, assessment cadence, typed domain and unit, current, target, and projected quantities, severity, trend, confidence, horizon, retained evidence count, and direct measured reason.", "signature": "world.settlement.needs(filters?, cursor?, page_size?) -> query-page", "usage": "Read the latest Settlement-owned food, water, fuel, housing, storage, labor, maintenance, and development assessment without creating a goal or changing a gameplay owner. Supply settlement_id to select the settlement." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Fixed tick assessed.", "id": "assessment_tick", "required": true, "units": "fixed-ticks", "value_type": "unsigned-integer" }, { "description": "Durable assessment sequence count.", "id": "completed_assessment_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Forecast confidence.", "id": "confidence", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Current measured quantity.", "id": "current_quantity", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Typed settlement need domain.", "id": "domain", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Forecast horizon.", "id": "horizon_ticks", "required": true, "units": "fixed-ticks", "value_type": "unsigned-integer" }, { "description": "Next fixed tick when assessment may run.", "id": "next_assessment_tick", "required": true, "units": "fixed-ticks", "value_type": "unsigned-integer" }, { "description": "Quantity forecast at the configured horizon.", "id": "projected_quantity", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Direct measured explanation.", "id": "reason", "required": true, "units": null, "value_type": "string" }, { "description": "Settlement identity.", "id": "settlement_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Current Settlement owner revision.", "id": "settlement_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Shortfall severity.", "id": "severity", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Owner evidence stamps retained.", "id": "source_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Settlement revision used to compose the assessment.", "id": "source_settlement_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Data-authored target quantity.", "id": "target_quantity", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Improving, stable, or worsening forecast.", "id": "trend", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Quantity unit for current and target values.", "id": "unit", "required": true, "units": null, "value_type": "enumeration" } ], "id": "world.settlement.needs", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "query", "name": "Settlement needs", "namespace": "world.settlement", "owner": "game.settlement", "replacement": null, "side_effects": "none", "signature": "world.settlement.needs(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.settlement.needs.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns Settlement-owned dependency plans, requirement state, prerequisite count, and exact authoritative owner bindings.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "One exact Settlement lookup plus one bounded traversal of retained plans and requirements. Recurring planning and reconciliation use authored visit, dependency, mutation, history, and cadence budgets.", "examples": [ "local plans = world.query(\"world.settlement.plans\", {filters = {settlement_id = 1}, page_size = 32})" ], "history": [ "1.19.0: Settlement-owned dependency plans and authoritative execution bindings added for Phase 19Q3." ], "id": "world.settlement.plans", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [ "filters.settlement_id: required stable Settlement identity.", "cursor: optional continuation cursor over requirements in stable plan and requirement order.", "page_size: bounded requirement-row limit." ], "related": [ "world.settlement.goals", "world.settlement.needs", "world.project.proposals", "world.construction.progress", "world.query" ], "returns": "Detached requirement rows with stable plan, goal, method, and requirement identities; plan and requirement status; dependency and alternative metadata; authored target; direct reason; and the exact authoritative owner binding when one exists.", "signature": "world.settlement.plans(filters?, cursor?, page_size?) -> query-page", "usage": "Inspect the Settlement-owned dependency plans that connect committed goals to current land, Resource, Production, Work, Infrastructure, Construction, and Building facts. The query is detached and cannot advance or cancel a requirement." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Alternative choice group or empty string.", "id": "alternative_group", "required": true, "units": null, "value_type": "string" }, { "description": "Bound authoritative owner kind.", "id": "binding_kind", "required": false, "units": null, "value_type": "enumeration-or-null" }, { "description": "Observed owner revision.", "id": "binding_owner_revision", "required": false, "units": null, "value_type": "revision-or-null" }, { "description": "Bound owner identity.", "id": "binding_stable_id", "required": false, "units": null, "value_type": "stable-id-or-null" }, { "description": "Direct state or blocker reason.", "id": "detail", "required": true, "units": null, "value_type": "string" }, { "description": "Durable source goal identity.", "id": "goal_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Data-authored source goal identity.", "id": "goal_key", "required": true, "units": null, "value_type": "string" }, { "description": "Data-authored planning method identity.", "id": "method_key", "required": true, "units": null, "value_type": "string" }, { "description": "Durable dependency plan identity.", "id": "plan_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Current dependency plan revision.", "id": "plan_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Current dependency plan status.", "id": "plan_status", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Number of prerequisite requirements.", "id": "prerequisite_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Durable requirement identity.", "id": "requirement_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Data-authored requirement identity.", "id": "requirement_key", "required": true, "units": null, "value_type": "string" }, { "description": "Domain owner required for execution.", "id": "requirement_kind", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Current requirement state.", "id": "requirement_status", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Settlement identity.", "id": "settlement_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Current Settlement owner revision.", "id": "settlement_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Data-authored target reference.", "id": "target_reference", "required": true, "units": null, "value_type": "string" }, { "description": "Last requirement update tick.", "id": "updated_at_tick", "required": true, "units": "fixed-ticks", "value_type": "unsigned-integer" } ], "id": "world.settlement.plans", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "query", "name": "Settlement plans", "namespace": "world.settlement", "owner": "game.settlement", "replacement": null, "side_effects": "none", "signature": "world.settlement.plans(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.settlement.plans.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns the latest Settlement-owned production alternatives, physical feasibility, scores, selection, and exact Production owner bindings.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "One exact Settlement lookup plus one bounded traversal of the latest retained production-option page. Recurring composition uses authored opportunity, selection, and cadence budgets and reads only current owner facts.", "examples": [ "local options = world.query(\"world.settlement.production-options\", {filters = {settlement_id = 1}, page_size = 16})" ], "history": [ "1.19.0: Dynamic production alternatives, direct feasibility evidence, cross-portfolio supply coordination, and exact Production bindings added for Phase 19Q4B1." ], "id": "world.settlement.production-options", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [ "filters.settlement_id: required stable Settlement identity.", "cursor: optional continuation cursor over options in stable policy-key order.", "page_size: bounded option-row limit." ], "related": [ "world.settlement.goals", "world.settlement.plans", "world.settlement.supply-options", "world.work.targets", "world.query" ], "returns": "Detached option rows with decision cadence and budget counts; recipe, building, material source, output, quantity, eligible labor, condition, capacity, route, goal-support, and active direct-supply evidence; deterministic score and rejection; selection; and the exact Production order identity and revision when bound.", "signature": "world.settlement.production-options(filters?, cursor?, page_size?) -> query-page", "usage": "Inspect the Settlement-owned production alternatives considered during its latest strategy evaluation. The query is detached and cannot create, claim, advance, or cancel Production or Work." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Active direct Supply commitments for the same need.", "id": "active_direct_supply_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Usable input quantity.", "id": "available_input_quantity", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Unreserved capacity.", "id": "available_service_capacity", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Observed condition.", "id": "building_condition", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Building definition identity.", "id": "building_definition_id", "required": true, "units": null, "value_type": "string" }, { "description": "Observed building identity.", "id": "building_id", "required": false, "units": null, "value_type": "stable-id-or-null" }, { "description": "Observed building revision.", "id": "building_revision", "required": false, "units": null, "value_type": "revision-or-null" }, { "description": "Alternatives visited.", "id": "candidate_visit_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Current household output.", "id": "current_output_quantity", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Direct selection or rejection explanation.", "id": "detail", "required": true, "units": null, "value_type": "string" }, { "description": "Feasible alternatives.", "id": "eligible_candidate_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Living adult settlement labor observed for the strategy horizon.", "id": "eligible_labor_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Fixed tick evaluated.", "id": "evaluation_tick", "required": true, "units": "fixed-ticks", "value_type": "unsigned-integer" }, { "description": "Active plan support.", "id": "goal_support", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Output resource identity.", "id": "output_resource_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Data-authored production opportunity identity.", "id": "policy_key", "required": true, "units": null, "value_type": "string" }, { "description": "Bound Production order.", "id": "production_order_id", "required": false, "units": null, "value_type": "stable-id-or-null" }, { "description": "Bound order revision.", "id": "production_order_revision", "required": false, "units": null, "value_type": "revision-or-null" }, { "description": "Recipe definition identity.", "id": "recipe_definition_id", "required": true, "units": null, "value_type": "string" }, { "description": "Direct ineligibility reason or none.", "id": "rejection", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Required input quantity.", "id": "required_input_quantity", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Recipe capacity need.", "id": "required_service_capacity", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Observed route cost.", "id": "route_cost_ticks", "required": true, "units": "fixed-ticks", "value_type": "unsigned-integer" }, { "description": "Deterministic option score.", "id": "score", "required": true, "units": "basis-points", "value_type": "signed-integer" }, { "description": "Whether Settlement selected this option.", "id": "selected", "required": true, "units": null, "value_type": "boolean" }, { "description": "Selected alternatives.", "id": "selected_candidate_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Settlement identity.", "id": "settlement_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Current Settlement owner revision.", "id": "settlement_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Material source identity.", "id": "source_container_id", "required": false, "units": null, "value_type": "stable-id-or-null" }, { "description": "Material source revision.", "id": "source_revision", "required": false, "units": null, "value_type": "revision-or-null" }, { "description": "Settlement revision used to compose the decision.", "id": "source_settlement_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Authored output target.", "id": "target_output_quantity", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Fixed-point production reasoner tuning version.", "id": "tuning_version", "required": true, "units": null, "value_type": "unsigned-integer" } ], "id": "world.settlement.production-options", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "query", "name": "Settlement production options", "namespace": "world.settlement", "owner": "game.settlement", "replacement": null, "side_effects": "none", "signature": "world.settlement.production-options(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.settlement.production-options.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns paginated detached quantities physically held in one Settlement's stockpiles.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "One bounded Settlement lookup, one visit per retained stockpile and stored resource amount, and one Resource lookup per returned row, all charged to the package query budget.", "examples": [ "local result = world.query(\"world.settlement.resources\", {\n page_size = 16,\n filters = {settlement_id = settlement.settlement_id}\n})\nif result.status == \"completed\" then\n for _, resource in ipairs(result.records) do\n ui.row(resource.display_name, tostring(resource.total))\n end\nend" ], "history": [ "1.5.0: Added a Settlement-owned stockpile view for player-facing store panels." ], "id": "world.settlement.resources", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [ "filters.settlement_id: required positive Settlement identity.", "cursor: optional continuation cursor indexing stable Resource identity order.", "page_size: positive record limit capped by the host." ], "related": [ "world.settlement", "world.settlement.for-actor", "world.resource.counts", "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation", "world.query" ], "returns": "Detached stored-resource rows containing Settlement and Resource identities, authored key and display name, total stockpile quantity, available quantity, and reserved quantity.", "signature": "world.settlement.resources(filters?, cursor?, page_size?) -> query-page", "usage": "Query one settlement_id to read only the resources physically retained in that Settlement's owned stockpiles. Use these records for settlement-store panels; do not substitute world-wide totals." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Unreserved stockpile quantity.", "id": "available", "required": true, "units": "resource-units", "value_type": "unsigned-integer" }, { "description": "Player-facing authored resource name.", "id": "display_name", "required": true, "units": null, "value_type": "string" }, { "description": "Authored resource key.", "id": "key", "required": true, "units": null, "value_type": "string" }, { "description": "Reserved stockpile quantity.", "id": "reserved", "required": true, "units": "resource-units", "value_type": "unsigned-integer" }, { "description": "Resource identity.", "id": "resource_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Settlement identity.", "id": "settlement_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Quantity held in Settlement stockpiles.", "id": "total", "required": true, "units": "resource-units", "value_type": "unsigned-integer" } ], "id": "world.settlement.resources", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "query", "name": "Settlement stored resources", "namespace": "world.settlement", "owner": "game.settlement, game.resource-economy, and assets.runtime-content-catalog", "replacement": null, "side_effects": "none", "signature": "world.settlement.resources(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.settlement.resources.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns active supply alerts for one supply chain.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "Bounded by page size, per-package query budget, and the owning snapshot builder; results are detached before Lua receives them.", "examples": [ "local result = world.query(\"world.settlement.shortages\", {page_size = 16})\nif result.status == \"completed\" then\n for _, record in ipairs(result.records) do\n -- Render or inspect detached record fields here.\n end\nend" ], "history": [ "1.0.0: Runtime contract published from the complete Phase 14 registry." ], "id": "world.settlement.shortages", "manual_nodes": [ "phase.14", "engine-reference.extension-contract" ], "parameters": [ "filters: optional table of query-specific stable IDs and bounded selectors.", "cursor: optional opaque continuation cursor returned by the same query.", "page_size: optional positive record limit capped by the host." ], "related": [ "world.settlement", "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation", "world.query" ], "returns": "A detached query page with status, records, continuation metadata, and a stable diagnostic when the request cannot complete.", "signature": "world.settlement.shortages(filters?, cursor?, page_size?) -> query-page", "usage": "Call this query through world.query with the stable ID world.settlement.shortages. Consume detached records during the current callback and use the returned cursor for bounded continuation." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Alert cause.", "id": "cause", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Alert kind.", "id": "kind", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Tick when the alert was raised.", "id": "raised_at_tick", "required": true, "units": "fixed-ticks", "value_type": "unsigned-integer" }, { "description": "Supply chain identity.", "id": "supply_id", "required": true, "units": null, "value_type": "stable-id" } ], "id": "world.settlement.shortages", "introduced": { "display": "1.0.0", "major": 1, "minor": 0, "patch": 0 }, "kind": "query", "name": "Settlement shortages", "namespace": "world.settlement", "owner": "game.settlement-supply", "replacement": null, "side_effects": "none", "signature": "world.settlement.shortages(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.settlement.shortages.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns recent completed village conversations, support, and disagreements.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "One bounded reverse Incident traversal plus one Relationship and authored-name lookup per returned row.", "examples": [ "local chronicle = world.query(\"world.settlement.social-chronicle\", {page_size = 3})" ], "history": [ "1.10.0: Retained village social chronicle added for Village Life addendum D." ], "id": "world.settlement.social-chronicle", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [ "cursor: optional continuation cursor.", "page_size: bounded encounter-row limit." ], "related": [ "world.actor.relationships", "world.settlement.list", "world.query" ], "returns": "Newest-first detached encounter rows with the Incident, tick, Site, two named participants, interaction kind, relationship stage, and latest relationship reason.", "signature": "world.settlement.social-chronicle(filters?, cursor?, page_size?) -> query-page", "usage": "Read the newest completed village conversations, support, and disagreements for the normal settlement chronicle without opening or changing an Incident." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "First participant identity.", "id": "first_actor_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "First participant display name.", "id": "first_display_name", "required": true, "units": null, "value_type": "string" }, { "description": "Completed social incident identity.", "id": "incident_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Conversation, support, or disagreement.", "id": "interaction", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Latest relationship change reason.", "id": "last_reason", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Tick when the encounter occurred.", "id": "occurred_at_tick", "required": true, "units": "ticks", "value_type": "unsigned-integer" }, { "description": "Relationship stage after the encounter.", "id": "relationship_stage", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Second participant identity.", "id": "second_actor_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Second participant display name.", "id": "second_display_name", "required": true, "units": null, "value_type": "string" }, { "description": "Encounter World-grid X coordinate.", "id": "site_cell_x", "required": true, "units": "grid-cells", "value_type": "signed-integer" }, { "description": "Encounter World-grid Y coordinate.", "id": "site_cell_y", "required": true, "units": "grid-cells", "value_type": "signed-integer" }, { "description": "Site where the encounter occurred.", "id": "site_id", "required": true, "units": null, "value_type": "stable-id" } ], "id": "world.settlement.social-chronicle", "introduced": { "display": "1.10.0", "major": 1, "minor": 10, "patch": 0 }, "kind": "query", "name": "Village social chronicle", "namespace": "world.settlement", "owner": "game.intersection-lifecycle, game.relationship, and authored settlement", "replacement": null, "side_effects": "none", "signature": "world.settlement.social-chronicle(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.settlement.social-chronicle.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns descriptive districts inferred by Settlement from current physical anchor proximity and services. District rows are read-only descriptions, not land authority.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "One exact Settlement lookup plus one bounded traversal of the latest retained district descriptions. Runtime derivation uses the authored district visit budget and proximity radius.", "examples": [ "local districts = world.query(\"world.settlement.spatial-districts\", {filters = {settlement_id = 1}, page_size = 16})\nfor _, district in ipairs(districts.records) do\n ui.text(district.kind, district.anchor_cells)\nend" ], "history": [ "1.19.0: Read-only physical-anchor district descriptions added for Phase 19Q6E." ], "id": "world.settlement.spatial-districts", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [ "filters.settlement_id: required stable Settlement identity.", "cursor: optional continuation cursor over stable district identities.", "page_size: bounded district-row limit." ], "related": [ "world.settlement.spatial-options", "world.settlement.spatial-executions", "world.infrastructure.local", "world.land.areas", "world.query" ], "returns": "Detached district rows with portfolio tick, stable key, descriptive kind, canonical anchor-cell list, distinct service list, Building and land-area counts, and direct derivation explanation. Residential-only districts may have an empty service list.", "signature": "world.settlement.spatial-districts(filters?, cursor?, page_size?) -> query-page", "usage": "Read the Settlement's latest descriptive grouping of current physical building and land anchors. Supply settlement_id. District descriptions do not claim land, set zoning, or authorize construction." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Stable comma-separated anchor-cell list.", "id": "anchor_cells", "required": true, "units": null, "value_type": "string" }, { "description": "Current physical anchors in the district.", "id": "anchor_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Current Building anchors.", "id": "building_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Direct district derivation explanation.", "id": "detail", "required": true, "units": null, "value_type": "string" }, { "description": "Stable descriptive district identity.", "id": "district_key", "required": true, "units": null, "value_type": "string" }, { "description": "Portfolio tick that described the district.", "id": "evaluation_tick", "required": true, "units": "fixed-ticks", "value_type": "unsigned-integer" }, { "description": "Residential, civic, agrarian, craft, or mixed description.", "id": "kind", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Current land-area anchors.", "id": "land_area_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Distinct services present.", "id": "service_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Stable comma-separated service list.", "id": "services", "required": true, "units": null, "value_type": "string" }, { "description": "Settlement identity.", "id": "settlement_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Current Settlement owner revision.", "id": "settlement_revision", "required": true, "units": null, "value_type": "revision" } ], "id": "world.settlement.spatial-districts", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "query", "name": "Settlement spatial districts", "namespace": "world.settlement", "owner": "game.settlement", "replacement": null, "side_effects": "none", "signature": "world.settlement.spatial-districts(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.settlement.spatial-districts.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns the bounded Settlement-owned lifecycle binding selected spatial options to authoritative Building Construction, Infrastructure Construction, or Land conversion.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "One exact Settlement lookup plus one bounded traversal of the retained spatial execution ledger. Runtime reconciliation visits only active executions under its authored budget.", "examples": [ "local executions = world.query(\"world.settlement.spatial-executions\", {filters = {settlement_id = 1}, page_size = 16})\nfor _, execution in ipairs(executions.records) do\n ui.text(execution.service, execution.status .. \": \" .. execution.detail)\nend" ], "history": [ "1.19.0: Durable spatial execution bindings, blockers, and authoritative outcomes added for Phase 19Q6E." ], "id": "world.settlement.spatial-executions", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [ "filters.settlement_id: required stable Settlement identity.", "cursor: optional continuation cursor over stable execution identities.", "page_size: bounded execution-row limit." ], "related": [ "world.settlement.spatial-options", "world.construction.progress", "world.infrastructure.construction", "world.land.areas", "world.query" ], "returns": "Detached execution rows with stable identity, source option and service, physical owner kind, optional owner identity, owner revision, active or terminal status, source portfolio tick, direct blocker or outcome, and creation and update ticks.", "signature": "world.settlement.spatial-executions(filters?, cursor?, page_size?) -> query-page", "usage": "Inspect the bounded Settlement-owned lifecycle that binds a selected spatial option to its authoritative physical owner. Supply settlement_id. The query cannot start, advance, cancel, or mutate the retained project." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Execution creation tick.", "id": "created_at_tick", "required": true, "units": "fixed-ticks", "value_type": "unsigned-integer" }, { "description": "Direct lifecycle, blocker, or outcome explanation.", "id": "detail", "required": true, "units": null, "value_type": "string" }, { "description": "Durable spatial execution identity.", "id": "execution_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Selected spatial option identity.", "id": "option_key", "required": true, "units": null, "value_type": "string" }, { "description": "Authoritative physical owner identity.", "id": "owner_id", "required": false, "units": null, "value_type": "stable-id-or-null" }, { "description": "Authoritative physical owner kind.", "id": "owner_kind", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Latest authoritative owner revision.", "id": "owner_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Selected spatial service.", "id": "service", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Settlement identity.", "id": "settlement_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Current Settlement owner revision.", "id": "settlement_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Portfolio evaluation used.", "id": "source_portfolio_evaluation_tick", "required": true, "units": "fixed-ticks", "value_type": "unsigned-integer" }, { "description": "Active, completed, blocked, cancelled, or failed.", "id": "status", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Latest lifecycle update tick.", "id": "updated_at_tick", "required": true, "units": "fixed-ticks", "value_type": "unsigned-integer" } ], "id": "world.settlement.spatial-executions", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "query", "name": "Settlement spatial executions", "namespace": "world.settlement", "owner": "game.settlement", "replacement": null, "side_effects": "none", "signature": "world.settlement.spatial-executions(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.settlement.spatial-executions.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns the latest Settlement-owned spatial service portfolio, including current coverage, every facility, field, or connection alternative, exact parcel or anchor evidence, selection, score, and direct rejection reason.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "One exact Settlement lookup plus one bounded traversal of the latest retained spatial portfolio. Runtime evaluation uses separately authored World-search, candidate, district, and mutation budgets.", "examples": [ "local options = world.query(\"world.settlement.spatial-options\", {filters = {settlement_id = 1}, page_size = 32})\nfor _, option in ipairs(options.records) do\n ui.text(option.service, tostring(option.current_capacity) .. \"/\" .. tostring(option.required_capacity) .. \": \" .. option.detail)\nend" ], "history": [ "1.19.0: Complete spatial service alternatives, physical location evidence, scores, selection, and direct rejection reasons added for Phase 19Q6E." ], "id": "world.settlement.spatial-options", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [ "filters.settlement_id: required stable Settlement identity.", "cursor: optional continuation cursor over stable option identities.", "page_size: bounded option-row limit." ], "related": [ "world.settlement.spatial-executions", "world.settlement.spatial-districts", "world.infrastructure.local", "world.land.areas", "world.query" ], "returns": "Detached option rows with portfolio cadence and counters, service and method identity, facility definition, optional road anchors, optional land area and parcel origin, source revisions, population and service capacity, materials, labor, competing work, travel, risk, score, selection or direct rejection, and explanation.", "signature": "world.settlement.spatial-options(filters?, cursor?, page_size?) -> query-page", "usage": "Inspect the latest Settlement-owned comparison of current road, water, storage, field, workshop, and public-space alternatives. Supply settlement_id. The query reports the exact current evidence but cannot select a site or start physical work." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Current competing physical work.", "id": "active_competing_work_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Available unreserved material.", "id": "available_material_units", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Facility definition, or empty for roads and fields.", "id": "building_definition_id", "required": true, "units": null, "value_type": "string" }, { "description": "Complete alternatives visited.", "id": "candidate_visits", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Current service capacity.", "id": "current_capacity", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Direct selection or rejection explanation.", "id": "detail", "required": true, "units": null, "value_type": "string" }, { "description": "Feasible alternatives before portfolio selection.", "id": "eligible_candidate_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Current eligible labor.", "id": "eligible_labor_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Fixed tick evaluated.", "id": "evaluation_tick", "required": true, "units": "fixed-ticks", "value_type": "unsigned-integer" }, { "description": "First connection anchor identity.", "id": "first_anchor_id", "required": false, "units": null, "value_type": "stable-id-or-null" }, { "description": "First connection anchor kind.", "id": "first_anchor_kind", "required": false, "units": null, "value_type": "enumeration-or-null" }, { "description": "First anchor cell x.", "id": "first_anchor_x", "required": false, "units": "world-cells", "value_type": "signed-integer-or-null" }, { "description": "First anchor cell y.", "id": "first_anchor_y", "required": false, "units": "world-cells", "value_type": "signed-integer-or-null" }, { "description": "Committed goal required by this spatial method.", "id": "goal_key", "required": true, "units": null, "value_type": "string" }, { "description": "Infrastructure evidence revision.", "id": "infrastructure_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Candidate World land-area identity.", "id": "land_area_id", "required": false, "units": null, "value_type": "stable-id-or-null" }, { "description": "Authored travel limit.", "id": "maximum_travel_ticks", "required": true, "units": "fixed-ticks", "value_type": "unsigned-integer" }, { "description": "Data-authored spatial method identity.", "id": "method_key", "required": true, "units": null, "value_type": "string" }, { "description": "Stable spatial option identity.", "id": "option_key", "required": true, "units": null, "value_type": "string" }, { "description": "Candidate facility origin x.", "id": "parcel_origin_x", "required": false, "units": "world-cells", "value_type": "signed-integer-or-null" }, { "description": "Candidate facility origin y.", "id": "parcel_origin_y", "required": false, "units": "world-cells", "value_type": "signed-integer-or-null" }, { "description": "Population used for service demand.", "id": "population", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Direct portfolio result.", "id": "portfolio_detail", "required": true, "units": null, "value_type": "string" }, { "description": "Direct feasibility or portfolio result.", "id": "rejection", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Required service capacity.", "id": "required_capacity", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Physical material requirement.", "id": "required_material_units", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Resource evidence revision.", "id": "resource_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Authored spatial risk.", "id": "risk", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Fixed-point portfolio score.", "id": "score", "required": true, "units": "basis-points", "value_type": "signed-integer" }, { "description": "Second connection anchor identity.", "id": "second_anchor_id", "required": false, "units": null, "value_type": "stable-id-or-null" }, { "description": "Second connection anchor kind.", "id": "second_anchor_kind", "required": false, "units": null, "value_type": "enumeration-or-null" }, { "description": "Second anchor cell x.", "id": "second_anchor_x", "required": false, "units": "world-cells", "value_type": "signed-integer-or-null" }, { "description": "Second anchor cell y.", "id": "second_anchor_y", "required": false, "units": "world-cells", "value_type": "signed-integer-or-null" }, { "description": "Whether this option was selected.", "id": "selected", "required": true, "units": null, "value_type": "boolean" }, { "description": "Road, water, storage, field, workshop, or public-space service.", "id": "service", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Settlement identity.", "id": "settlement_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Current Settlement owner revision.", "id": "settlement_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Settlement revision used to evaluate the portfolio.", "id": "source_settlement_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Current access travel.", "id": "travel_ticks", "required": true, "units": "fixed-ticks", "value_type": "unsigned-integer" }, { "description": "Work evidence revision.", "id": "work_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "World evidence revision.", "id": "world_revision", "required": true, "units": null, "value_type": "revision" } ], "id": "world.settlement.spatial-options", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "query", "name": "Settlement spatial options", "namespace": "world.settlement", "owner": "game.settlement", "replacement": null, "side_effects": "none", "signature": "world.settlement.spatial-options(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.settlement.spatial-options.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns the latest Settlement-owned physical supply alternatives, direct rejection reasons, scores, selections, and exact Supply owner bindings.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "One exact Settlement lookup plus one bounded traversal of the latest retained supply-option page. Recurring composition uses authored Settlement, source, candidate, mutation, history, and cadence budgets.", "examples": [ "local options = world.query(\"world.settlement.supply-options\", {filters = {settlement_id = 1}, page_size = 32})" ], "history": [ "1.19.0: Dynamic physical supply alternatives, direct rejection evidence, and exact Supply bindings added for Phase 19Q4A." ], "id": "world.settlement.supply-options", "manual_nodes": [ "phase.19", "engine-reference.extension-contract" ], "parameters": [ "filters.settlement_id: required stable Settlement identity.", "cursor: optional continuation cursor over options in stable option-ID order.", "page_size: bounded option-row limit." ], "related": [ "world.settlement.needs", "world.settlement.plans", "world.settlement.resources", "world.work.targets", "world.query" ], "returns": "Detached option rows with portfolio cadence and budget counts; demand, beneficiary, resource, container, and Site identities; observed quantity, capacity, route, danger, need, gap, relief, re-entry, urgency, and alert facts; deterministic score and rejection; selection; and the exact Supply identity and revision when bound.", "signature": "world.settlement.supply-options(filters?, cursor?, page_size?) -> query-page", "usage": "Inspect the Settlement-owned physical food, water, fuel, and development-material alternatives considered during its latest supply evaluation. The query is detached and cannot create, claim, or advance Supply or Work." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Available source quantity.", "id": "available_quantity", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Resident beneficiary for need supply.", "id": "beneficiary_id", "required": false, "units": null, "value_type": "stable-id-or-null" }, { "description": "Physical source alternatives visited by the bounded reasoner.", "id": "candidate_visit_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Durable supply portfolio sequence count.", "id": "completed_evaluation_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Quantity consumed by one need-supply execution.", "id": "consumption_quantity", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Physical destination container identity.", "id": "destination_container_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Observed free destination capacity.", "id": "destination_free_quantity", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Physical destination site identity.", "id": "destination_site_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Direct selection or rejection explanation.", "id": "detail", "required": true, "units": null, "value_type": "string" }, { "description": "Settlement need domain.", "id": "domain", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Alternatives that passed every hard eligibility gate.", "id": "eligible_candidate_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Fixed tick evaluated.", "id": "evaluation_tick", "required": true, "units": "fixed-ticks", "value_type": "unsigned-integer" }, { "description": "Material supply job urgency.", "id": "job_urgency", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Need threshold that permits repeat execution.", "id": "need_reentry", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Need relief per execution.", "id": "need_relief", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Current demand severity.", "id": "need_severity", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Next fixed tick when evaluation may run.", "id": "next_evaluation_tick", "required": true, "units": "fixed-ticks", "value_type": "unsigned-integer" }, { "description": "Durable physical option identity.", "id": "option_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Data-authored demand policy identity.", "id": "policy_key", "required": true, "units": null, "value_type": "string" }, { "description": "Food, water, or material execution purpose.", "id": "purpose", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Direct ineligibility reason or none.", "id": "rejection", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Requested transfer quantity.", "id": "requested_quantity", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Resource owner identity.", "id": "resource_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Observed route cost.", "id": "route_cost_ticks", "required": true, "units": "fixed-ticks", "value_type": "unsigned-integer" }, { "description": "Observed route danger.", "id": "route_danger", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "Deterministic option score.", "id": "score", "required": true, "units": "basis-points", "value_type": "signed-integer" }, { "description": "Whether Settlement selected this option.", "id": "selected", "required": true, "units": null, "value_type": "boolean" }, { "description": "Alternatives selected for normal Supply execution.", "id": "selected_candidate_count", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Settlement identity.", "id": "settlement_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Current Settlement owner revision.", "id": "settlement_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Physical source container identity.", "id": "source_container_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Need assessment used as source evidence.", "id": "source_need_assessment_tick", "required": true, "units": "fixed-ticks", "value_type": "unsigned-integer" }, { "description": "Settlement revision used to compose the portfolio.", "id": "source_settlement_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Physical source site identity.", "id": "source_site_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Observed stock shortfall.", "id": "stock_gap_quantity", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Bound Supply owner identity.", "id": "supply_id", "required": false, "units": null, "value_type": "stable-id-or-null" }, { "description": "Bound Supply owner revision.", "id": "supply_revision", "required": false, "units": null, "value_type": "revision-or-null" }, { "description": "Fixed-point supply portfolio tuning version.", "id": "tuning_version", "required": true, "units": null, "value_type": "unsigned-integer" }, { "description": "Delay before an unfilled supply alerts.", "id": "unfilled_alert_after_ticks", "required": true, "units": "fixed-ticks", "value_type": "unsigned-integer" } ], "id": "world.settlement.supply-options", "introduced": { "display": "1.19.0", "major": 1, "minor": 19, "patch": 0 }, "kind": "query", "name": "Settlement supply options", "namespace": "world.settlement", "owner": "game.settlement", "replacement": null, "side_effects": "none", "signature": "world.settlement.supply-options(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.settlement.supply-options.html" }, { "authority": "read_only", "availability": "runtime API 1", "deprecated": null, "description": "Detached actionable Work targets and current assignments.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Constant-time namespace lookup.", "examples": [ "-- Query world.work.targets or world.work.assignment." ], "history": [ "1.5.0: Player Work inspection namespace added for Phase 16D." ], "id": "world.work", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [], "related": [ "world.work.targets", "world.work.assignment", "world.query" ], "returns": "The registered Work query contracts.", "signature": "namespace world.work", "usage": "Use this namespace to inspect actionable work targets and the current player assignment. The namespace has no mutation authority." }, "errors": [], "fields": [], "id": "world.work", "introduced": { "display": "1.5.0", "major": 1, "minor": 5, "patch": 0 }, "kind": "namespace", "name": "Work direction queries", "namespace": "world.work", "owner": "game.work-lifecycle", "replacement": null, "side_effects": "none", "signature": "namespace world.work", "source_location": "src/app/script_api_catalog.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.work.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns the latest live player assignment retained for one Actor.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "One indexed live assignment lookup.", "examples": [ "local assignment = world.query(\"world.work.assignment\", {page_size = 1, filters = {actor_id = selected_id}})" ], "history": [ "1.5.0: Live player assignment query added for Phase 16D." ], "id": "world.work.assignment", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [ "filters.actor_id: required stable Actor identity.", "cursor: optional continuation cursor.", "page_size: bounded record limit." ], "related": [ "world.work", "command.work.cancel", "world.work.targets" ], "returns": "One detached live assignment row, or an empty completed page when no player assignment exists.", "signature": "world.work.assignment(filters?, cursor?, page_size?) -> query-page", "usage": "Query one actor_id to read that Actor's latest live player assignment order and current revision." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Assigned Actor identity.", "id": "actor_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Assigned job identity.", "id": "job_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Assignment-order identity.", "id": "order_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Current assignment-order revision.", "id": "order_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Current assignment state.", "id": "state", "required": true, "units": null, "value_type": "enumeration" } ], "id": "world.work.assignment", "introduced": { "display": "1.5.0", "major": 1, "minor": 5, "patch": 0 }, "kind": "query", "name": "Current work assignment", "namespace": "world.work", "owner": "game.work-lifecycle", "replacement": null, "side_effects": "none", "signature": "world.work.assignment(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.work.assignment.html" }, { "authority": "read_only", "availability": "active-session", "deprecated": null, "description": "Returns bounded detached gathering and construction jobs valid for one Actor.", "determinism": "stable owner order at the current committed tick", "documentation": { "cost": "Bounded settlement-local Work, Supply, Construction, Actor, and World visits.", "examples": [ "local targets = world.query(\"world.work.targets\", {page_size = 16, filters = {actor_id = selected_id}})" ], "history": [ "1.5.0: Actionable settlement work query added for Phase 16D." ], "id": "world.work.targets", "manual_nodes": [ "phase.16", "engine-reference.extension-contract" ], "parameters": [ "filters.actor_id: required stable Actor identity.", "cursor: optional continuation cursor.", "page_size: bounded target count." ], "related": [ "world.work", "command.work.assign", "command.work.set-priority" ], "returns": "Detached target rows with owner IDs, revisions, labels, type, Site, topology revision, and current player priority.", "signature": "world.work.targets(filters?, cursor?, page_size?) -> query-page", "usage": "Query one actor_id for gathering and construction work that can currently be directed through the normal assignment path. Use the returned revisions unchanged when submitting command.work.assign or command.work.set-priority." }, "errors": [ "error.capability-unavailable", "error.invalid-query", "error.query-budget-exhausted", "error.query-contract-violation" ], "fields": [ { "description": "Actor that can receive the direction.", "id": "actor_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Current Actor revision.", "id": "actor_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Player-facing target explanation.", "id": "detail", "required": true, "units": null, "value_type": "string" }, { "description": "Work job identity.", "id": "job_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Current job revision.", "id": "job_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "Gathering or construction.", "id": "kind", "required": true, "units": null, "value_type": "enumeration" }, { "description": "Player-facing target label.", "id": "label", "required": true, "units": null, "value_type": "string" }, { "description": "Durable player-priority contribution.", "id": "player_priority", "required": true, "units": "basis-points", "value_type": "unsigned-integer" }, { "description": "World Site for the work target.", "id": "target_site_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Current World topology revision.", "id": "topology_revision", "required": true, "units": null, "value_type": "revision" }, { "description": "First Work task identity.", "id": "work_task_id", "required": true, "units": null, "value_type": "stable-id" }, { "description": "Current task revision.", "id": "work_task_revision", "required": true, "units": null, "value_type": "revision" } ], "id": "world.work.targets", "introduced": { "display": "1.5.0", "major": 1, "minor": 5, "patch": 0 }, "kind": "query", "name": "Work targets", "namespace": "world.work", "owner": "game.work-lifecycle, game.settlement-supply, game.construction, game.actor-runtime, and sim.world-runtime", "replacement": null, "side_effects": "none", "signature": "world.work.targets(filters?, cursor?, page_size?) -> query-page", "source_location": "src/app/script_query_service.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world.work.targets.html" }, { "authority": "presentation", "availability": "runtime API 1", "deprecated": null, "description": "Host-owned presentation channels composed from detached world facts.", "determinism": "Stable namespace identity and normalized symbol order.", "documentation": { "cost": "Namespace lookup is constant-time and performs no owner visits.", "examples": [ "local channels = world_indicators.channels()" ], "history": [ "1.7.0: World-indicator presentation namespace added for the Phase 17A addendum." ], "id": "world_indicators", "manual_nodes": [ "phase.17", "engine-reference.extension-contract" ], "parameters": [], "related": [ "world_indicators.channels", "world_indicators.is-visible", "world_indicators.set-visible" ], "returns": "The channel discovery and visibility functions available to the calling package origin.", "signature": "namespace world_indicators", "usage": "Discover and control registered host-owned world-indicator channels. The namespace provides presentation controls only and never grants access to mutable simulation owners." }, "errors": [], "fields": [], "id": "world_indicators", "introduced": { "display": "1.7.0", "major": 1, "minor": 7, "patch": 0 }, "kind": "namespace", "name": "World indicators", "namespace": "world_indicators", "owner": "app.world-indicator-composition", "replacement": null, "side_effects": "none", "signature": "namespace world_indicators", "source_location": "src/app/script_api_catalog.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world_indicators.html" }, { "authority": "read_only", "availability": "Phase 14 package callbacks", "deprecated": null, "description": "Lists world-indicator channels available to the calling package.", "determinism": "Host-created package identity and per-callback budgets.", "documentation": { "cost": "One bounded traversal of the compiled channel registry.", "examples": [ "for _, channel in ipairs(world_indicators.channels()) do\n ui.row(channel.label, channel.visible and \"Visible\" or \"Hidden\")\nend" ], "history": [ "1.7.0: Bounded world-indicator channel discovery added." ], "id": "world_indicators.channels", "manual_nodes": [ "phase.17", "engine-reference.extension-contract" ], "parameters": [], "related": [ "world_indicators", "world_indicators.is-visible", "world_indicators.set-visible" ], "returns": "Stable channel records with id, label, audience, development_only, and visible fields.", "signature": "world_indicators.channels() -> channel[]", "usage": "List the stable indicator channels visible to the calling package origin before showing controls for them." }, "errors": [], "fields": [], "id": "world_indicators.channels", "introduced": { "display": "1.7.0", "major": 1, "minor": 7, "patch": 0 }, "kind": "function", "name": "channels", "namespace": "world_indicators", "owner": "app.ScriptPackageHost", "replacement": null, "side_effects": "none", "signature": "world_indicators.channels() -> channel[]", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world_indicators.channels.html" }, { "authority": "read_only", "availability": "Phase 14 package callbacks", "deprecated": null, "description": "Returns whether one available world-indicator channel is visible.", "determinism": "Host-created package identity and per-callback budgets.", "documentation": { "cost": "One indexed host-state lookup.", "examples": [ "local visible = world_indicators.is_visible(\"development.resource-activity\")" ], "history": [ "1.7.0: Per-session world-indicator visibility query added." ], "id": "world_indicators.is-visible", "manual_nodes": [ "phase.17", "engine-reference.extension-contract" ], "parameters": [ "channel_id: stable registered indicator-channel identity." ], "related": [ "world_indicators.channels", "world_indicators.set-visible", "error.indicator-channel-unavailable" ], "returns": "True when the channel is currently enabled; false when it is hidden.", "signature": "world_indicators.is_visible(channel_id) -> visible", "usage": "Read the current per-session visibility of one channel available to the calling package origin." }, "errors": [ "error.indicator-channel-unavailable" ], "fields": [], "id": "world_indicators.is-visible", "introduced": { "display": "1.7.0", "major": 1, "minor": 7, "patch": 0 }, "kind": "function", "name": "is_visible", "namespace": "world_indicators", "owner": "app.ScriptPackageHost", "replacement": null, "side_effects": "none", "signature": "world_indicators.is_visible(channel_id) -> visible", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world_indicators.is-visible.html" }, { "authority": "presentation", "availability": "Phase 14 package callbacks", "deprecated": null, "description": "Changes per-session visibility for one authorized world-indicator channel.", "determinism": "Host-created package identity and per-callback budgets.", "documentation": { "cost": "One indexed host-state update; owner facts are composed later only while the channel is visible.", "examples": [ "world_indicators.set_visible(\"development.resource-activity\", true)" ], "history": [ "1.7.0: Authorized per-session world-indicator visibility control added." ], "id": "world_indicators.set-visible", "manual_nodes": [ "phase.17", "engine-reference.extension-contract" ], "parameters": [ "channel_id: stable registered indicator-channel identity.", "visible: requested presentation visibility." ], "related": [ "world_indicators.channels", "world_indicators.is-visible", "error.indicator-channel-authority", "error.indicator-channel-unavailable" ], "returns": "True after the host accepts the visibility value.", "signature": "world_indicators.set_visible(channel_id, visible) -> changed", "usage": "Show or hide one authorized indicator channel for the current session. Use this for explicit lens controls, not as a gameplay-state switch." }, "errors": [ "error.indicator-channel-authority", "error.indicator-channel-unavailable" ], "fields": [], "id": "world_indicators.set-visible", "introduced": { "display": "1.7.0", "major": 1, "minor": 7, "patch": 0 }, "kind": "function", "name": "set_visible", "namespace": "world_indicators", "owner": "app.ScriptPackageHost", "replacement": null, "side_effects": "changes host-owned presentation visibility without mutating simulation state", "signature": "world_indicators.set_visible(channel_id, visible) -> changed", "source_location": "src/app/script_package_host.cpp", "timing": "immediate", "units": null, "url": "/api/v1/symbols/world_indicators.set-visible.html" } ] }