PlatinumSDK modules in everyday use
This guide connects the Runtime's visible behavior to the SDK modules behind it. It is a practical map for application makers, rather than the full runtime API. Source links point to the implementation and examples used for this edition. Applications enable only the modules they need; game tools are not a mandatory dependency for writing a document application.
Choose an application starting point
| Starting point | What you supply | What it gives you | Example |
|---|---|---|---|
| A document application | Application identity, menus, initial document and your tools | Independent document windows, file results, close/save flow and workspace integration | Platinum Write, notebook |
| A custom desktop tool | Your state, panel registrations and drawing callback | Native or docked tool panels around an application-owned main view | custom panels |
| An editor embedded in another application | An editor model and a place to draw it | Rich document editing without replacing your whole application | embedded editor |
| A scene/game application | Project data, assets, Event Tables and Lua behavior | Game UI, scene lifecycle, simulation and selected rendering/network modules | game bootstrap, Creator guide |
| A headless service | Authenticated commands, data schemas and a storage provider | Renderer-free domain/authority operations | authority host, server contract |
office::application is the desktop document/tool host. The separate application(AppDescriptor) entry point starts the lower-level retained Bevy UI route. Mixing the two without understanding their camera and focus ownership can create duplicate presentation work. Start from the example closest to your application.
Documents, editing and interchange
rich_text, editor, formats and workspace separate document data, editing state, interchange and application lifecycle. A document is more than the currently visible text: formatting, embedded objects, tables and layout also belong to its model. A view has its own caret, selection, zoom and editing state.
| Module | Input | Output or event | Lifecycle and practical use |
|---|---|---|---|
rich_text | A RichDocument, style runs and user edits | Updated document/editor state | Use character-aware selections; do not treat byte offsets as character positions. |
editor | Document state and editor commands | Rendered editor, command effects, dirty/history state | Keep document ownership with the host. Close follows save/cancel decisions. |
formats | File name plus bounded bytes | ImportedDocument { document, warnings } or an error | Read warnings when importing. Supported interchange is not a promise of pixel-perfect foreign-format fidelity. |
platform::FileService | Open/save/import requests | Opened, ImageLoaded, Saved, Cancelled or Error results | Consume asynchronous results in the application loop. A request is not a completed save. |
workspace | WorkspaceConfig, registered panels and file results | Owned document/dialog windows and workspace commands | Use this when you want a complete multi-document host. |
live_text | Accepted sequence snapshots/commits and view-local edits | Shared text, preserved drafts and durable save state | Keep local pending edits when the authority cannot accept a change. |
script_editor, lua_api | Shared source text, document revision and versioned declarations | Syntax overlays, completion and diagnostics | Analysis belongs to a worker. Display results only for the revision they describe. |
A bounded import already exists:
use platinum_sdk::formats::decode_document;
fn import_markdown(bytes: &[u8]) -> Result<String, String> {
let imported = decode_document("notes.md", bytes)?;
// Surface imported.warnings in your application's import result.
Ok(imported.document.text)
}This imports data; it does not authorize a filesystem write or install an application. The decoder accepts OpenDocument and UTF-8 document routes, including Markdown, with a 32 MiB package bound in this implementation. See format source, Live Text and recoverable saves.
Files and spatial objects
file_manager supplies folder/list models, filesystem adapters, selection, navigation and native folder windows. Files and views retain identities across the workflow rather than turning every representation into an unrelated document copy. A file operation still needs permission and an actual successful filesystem result.
Platinum Files starts with the native folder application and shares document-window integration with Write. It accepts an initial folder; otherwise it uses the home directory and saved folder restoration. It requires native filesystem/window access. The example does not make the full desktop filesystem available to a browser application.
The reusable folder list and host-owned filesystem adapter are separate. Applications can present a list without granting arbitrary disk access. The shared folder view describes identity, selection and authorized data behavior; Finder requirements also contain proposed work and must not be read as a list of shipped features.
content_provider exposes admitted read-only content indexes and bounded ranges. thumbnail_cache uses those admitted views to decode previews asynchronously. A path, asset hash or cache label is not a permission. If an access gate is revoked or a result is stale, keep that outcome visible instead of reusing an old preview as proof of access. See thumbnail cache.
Reusable authoring tools
These controls are useful beyond game development. They accept application-owned data and return commands; the host checks the latest document revision before applying them.
| Tool | Input | Output | Useful for |
|---|---|---|---|
authoring::hierarchy | Stable object IDs and parent relationships | Selection and hierarchy commands | Scene trees, document outlines and project structure |
authoring::inspector | Named typed properties and editability | Property edit gestures/commands | Object properties and control panels |
authoring::timeline | Tracks, keys and a local view | Key/track/time editing commands | Animation, media timing and sequenced work |
authoring::history | Application snapshots/transactions | Bounded undo/redo history | Making a completed gesture one undoable action |
node_editor | Nodes, typed application ports and links | Canvas navigation/selection/link gestures | Material graphs, behaviors and other connected models |
live_data | JSON-like application data and an editable/read-only choice | Inspected data edits | Simple live model inspection without a new domain editor |
Use authoring_tools.rs for a working non-game composition. Gesture::begin, preview, cancel and commit let an application preview many changes but commit only one undoable change. The controls do not supply domain authority, collaborative undo, universal accessibility or a fully virtualized arbitrary hierarchy by themselves.
UI definitions, tool windows and themes
The GUI guide covers widgets and examples. The important distinction is between authored UI data and a host's window presentation. A UI document describes elements, values and action bindings; a native host decides which windows exist and which tool palettes are docked, floating or pinned.
panels provides application-owned registrations, PanelPreferences, docking and native surface lifecycle. A panel cannot be restored into an application merely because a saved file contains its ID: it must be registered first. Pinning keeps a registered native tool visible on application focus loss; it does not grant data access or duplicate an application main view. The custom panels example shows the minimal ownership loop.
office supplies classic chrome and host surfaces; ui supplies the retained Bevy control route. contained_layout guards presentation when a canvas has no usable region. input clears held input/capture at focus boundaries so a background application does not keep acting on a previously held key.
theme contains validated theme data, button feedback and an opt-in modern renderer. An application's preference and a forced system default are separate choices. Theme assets are data, not scripts and not publisher verification. The renderer-free desktop theme_settings module supplies durable settings planning/validation; an actual host must apply those settings. See theme implementation and theme asset contract.
window_resources measures selected tool-window CPU draw work and offers resource advice. It distinguishes measured costs from estimated memory and does not claim GPU timings or guaranteed frame-rate improvement. Closing an unused preview can help, but a pinned or essential tool must not be treated as disposable merely because it has a window.
Live models, saved state and recovery
The Runtime aims to make multiple views feel like portals to one object. Implementation has several explicit layers:
| Layer | Inputs | Outputs and guarantees to preserve |
|---|---|---|
schema, binding | Validated schemas, registered model roots and typed fields | Consistent model access and schema-aware validation; names alone do not grant access |
tracked | Registered root changes and policy | Bounded snapshots/patch packets with revisions |
platinum-sync, SDK state_sync | Tracked roots, pacing and an authority port | Submission, pending state, retry/backpressure and acknowledgment handling |
live, LiveAuthority | Authenticated connections, scoped grants and transactions | Accepted snapshots/commits/replay or rejection |
live_assets | An authorized binding, validator and authority port | Shared accepted asset projections, previews and retained failed drafts |
live_text | Shared accepted text with view-local state | Text editing and recovery semantics without duplicating authority |
platinum-lua, SDK live_lua | A registered model and read/write permissions | Revision-checked live userdata plus explicitly detached snapshots |
A submitted edit is not a durable acknowledgment. A replayed snapshot that happens to match an uncertain operation is not an authoritative operation receipt. Keep unresolved writes pending until the correct receipt reconciles them. These distinctions protect work during crashes and reconnects.
Managed recovery covers declared persistent DTO/model roots and the state their applications actually register. It does not serialize arbitrary Rust pointers, OS handles, all Lua globals, coroutines or a process stack. Transient Play activity can intentionally remain transient. See tracked implementation, managed recovery, live asset contract and Live Objects.
Event Tables, animation and behavior
events describes typed, bounded Event Tables. A trigger has a schema and scope; handlers select behavior; actions still require authority at the side-effect boundary. Ownership inheritance is not permission inheritance. A mandatory trusted policy cannot be bypassed by a more specific behavior table.
In Creator, Event Tables can connect an authored action to Lua, animation and domain commands. Event metadata, event scopes and animation examples show the actual authoring workflow. Lua's engine.emit dispatches a named event; it is not a raw route to every host API.
The renderer-free animation module samples validated scalar animation from a host-owned clock and typed bindings. Sampling alone does not spawn objects, execute expressions, send notifications or authorize changes. Scene/UI adapters apply those samples to specific domains. Identical data and inputs are intended to produce consistent sampling within the same numerical environment; bitwise cross-platform replay is not promised.
Scenes, media and games
The optional game feature family contains substantial systems that a simple desktop document application does not need. Use the corresponding product guide for concrete setup.
| Module family | Input | Output/lifecycle | Guide |
|---|---|---|---|
| Projects, scenes, prefabs and assets | Project-relative asset documents and instance overrides | Validated scene instances, editor state and export dependencies | Creator, prefabs/export |
| Materials and particles | Material graphs, textures and effect documents | Rendered materials/effects with provider budgets; explicit fallback differences | materials, physics/particles |
| Audio | Sound assets, buses, cues and listener policy | Voices, attenuation and playback lifecycle | network audio |
| Characters and animation | Rigs, clips, pose graphs, attachments and drive settings | Poses, IK and physical animation under explicit ownership | characters, animations |
| Physics, locomotion, combat and equipment | Validated bodies, input and game commands | Simulation state and gameplay events | combat/physical animation, first-person |
| Modes, streaming and residency | Mode/level state and resource budgets | Loaded scene state and scoped transitions | modes/streaming, scene streaming |
| Testing and testing UI | Declared test cases and bounded harness inputs | Case results and inspectable failure evidence | testing, validation |
A scene asset and a running world are different sources. Scene data is the authored source of truth; a running session adds tick/epoch-specific activity. world_session, world_session_game and world_session_view separate projection data, a game adapter and read-only presentation. A view does not create a second authoritative simulation. See live world plan; its future topology must be distinguished from working projection APIs.
Networking and service boundaries
The renderer-free network module defines routing, bounds, queues and authenticated transport facts. It does not implement a socket or encryption engine by itself. Game transport adapters support selected native/browser, P2P and WebTransport arrangements depending on features; check the deployment guide for the configured route. Do not describe all adapters as having identical behavior or security.
spatial defines session/view, camera and audio policy. A camera can be local or follow/control a shared camera under a grant. A view's audio can be muted, focus-selected, explicitly monitored or mixed. Opening another view should not start another simulation or duplicate sound indiscriminately.
service supplies bounded embedded/thread provider contracts. runtime supplies scoped authority primitives. runtime_supervision adds native application supervision integration. Threads and process separation alone do not provide OS containment. The security chapter explains current guarantees, opt-outs and the future container topology.
security_controls negotiates global, application and peer tunnel policy. A global encryption requirement cannot be weakened by an application override. A peer may refuse either mode; refusal fails the connection instead of silently downgrading it. security_settings::SecuritySettingsEditor renders these values and returns validated Apply requests. The authoritative settings host must persist and install them; a reusable editor is not evidence that a system-wide daemon is running.
Packages, release identity and the Software Hub
A .pla is an indexed application container; an EXE/native module is executable machine code. Package parsing identifies inert content and dependencies. It does not prove a publisher's identity, grant permissions or make native code safe. The host combines application registry/release policy, authenticated verification results and the user's choices before admission. See application releases, desktop registry and security.
application_registry handles stable product identity and registration plans; application_release handles release metadata/policy. platinum-application-package handles container/export/presentation data. SDK application_package integrates the optional application host path. Native extensions should be reserved for extending a core capability unavailable through Lua and supported data APIs; they are not the intended first step for ordinary application behavior.
The Software Hub has distinct roles: discovering software, displaying products/purchases/licenses, serving developer publication workflows, and supplying authorized licensing/integrity information. Account ownership, catalog metadata and executable trust are different facts. The Hub/HR product source is maintained in its own owner checkout; use its fixed handoff for release integration, not just the SDK workspace member list. A purchase policy or integrity upload must not be inferred merely from an application appearing in a catalog.
Identity, accounts and business applications
PlatinumAuth provides account/login and deployment-owned identity services; it is also a separate application/deployment, not a mandatory assumption that every local tool has an online account. Provider connections, consent and administrator operations belong to the configured deployment. See Auth product (../auth/PRODUCT.md; main-checkout evidence in ), branded portals (../auth/BRANDED_PORTALS.md; main-checkout evidence in ), federation/recovery (../auth/FEDERATION_PASSWORD_FLOWS.md; main-checkout evidence in ) and deployment (../auth/DEPLOYMENT.md; main-checkout evidence in ).
Platinum Human Resources demonstrates the same framework in an application workflow: careers and applications, staff directories, roles, criteria/scorecards, tasks, proposals and controlled disclosure. Public applicants and staff have different permissions. Decisions remain human; assessment tools should not be described as automatic rejection. Its domain and host adapters are application-specific examples, not general Runtime primitives. Owner coverage and product integration are recorded in the HR/Hub handoff.
The low-level authority host, SQLite provider, schema daemon and state worker are service components. Most end users never call them directly. They support authenticated command processing, durable state, schema work and independent data processing under a host. The authority host contract and SQLite implementation are for integrators who need those details.
Reading the reference without mistaking a plan for a promise
Use the generated Lua/public API reference for exact names and signatures, and the linked worked examples for integration. Source comments and declaration catalogs must change with the binding implementation. A Rust public type is not automatically a Lua function, an Event Table action or a GUI data tag.
The coverage inventory records remaining manual/reference work, screenshot gates, and source-versus-plan distinctions: . In particular, generic LiveView/copy interfaces and a complete Runtime settings daemon are integration gaps until implemented and tested; the existing adapters must not be renamed into a universal guarantee.