Creating applications with PlatinumSDK

This is an orientation for users beginning to make software, not the full Runtime/API specification. Start with a small project, use the host's UI assets and Lua/Event Table facilities, and consult the public API reference when you need an exact call.

Why Lua?

Lua is small and designed to embed in other programs. Its readable control flow, tables and functions let a beginner make a useful behavior without first learning a native build system. Its long-standing use in games and tools makes it a practical foundation as well as an approachable one. Lua's own overview lists industrial uses including games and Lightroom.

Roblox demonstrates the reach of Lua-family scripting for young creators, but Roblox uses Luau, a derived language with its own APIs and differences. Platinum's Lua is not Roblox's engine, and Roblox scripts are not automatically compatible. See Roblox's documented Lua/Luau globals.

The ecosystem has several interpreter/JIT/compiler approaches; a host's chosen version and bindings determine compatibility and resource behavior. More scripting languages are planned. Do not assume Python, JavaScript, Luau or a different Lua implementation is already installed just because the architecture can grow.

Data, behavior, actions

Use a UI data file to describe a view, Lua for behavior and registered Event Tables/commands for actions. Keep important application state in declared managed models where recovery is needed. A random Lua global, coroutine stack, external socket or arbitrary Rust allocation is not automatically persistent.

The GUI tutorial creates a small form and manipulates it through existing game-host bindings. The same conceptual workflow applies to general applications, but the currently implemented generic UI presenter/loader must be checked for your host. The engine namespace is Game Creator's API; the renderer-free Lua model facade is separate.

A small Lua behavior in a host-supplied callback can be as simple as:

local function greeting(name)
    if name == "" then
        return "Hello!"
    end
    return "Hello, " .. name
end

Connect it through the host's documented event/action registration, then update a bound status value. Keep authorization in the command owner. A script may express an intention to save/share/connect, but cannot grant itself filesystem or network access.

Event Tables

Event Tables organize conditions and actions around scope, source and target. Game Creator's visual tables support authoring rules without hiding them inside GUI code. Shared event contracts preserve mandatory system behavior and security checks. An event received from another app is information, not an authorization token.

Scope matters: an object, level, mode or application may see a different event universe. Use readable metadata and declared targets; avoid broad “all objects” rules when a narrow source is intended. See the Event Table reference, event metadata guide and scope guide.

Build and export

A data-only update can package scripts, UI and assets against a compatible prebuilt host. Changes to native code or incompatible runtime/module versions require compilation. The CLI and Build & Export interface should describe the same effective inputs; a convenient wizard is not a different security policy.

In the existing Creator Build & Export workflow, save documents/assets and leave transient Play before exporting. Select the compatible prebuilt receipt, target and output folder. The exporter works from the saved disk snapshot; it does not quietly package unsent drafts. Inspect actionable errors rather than assuming a previous successful export represents the current editor state.

Protected export requires a configured protection/signing provider. Explicit development/open-data choices provide local testing, not a publisher-authenticated production release. Keep stable application identity separate from a new per-release build identity. Do not upload project sources or secrets just to check a GUID.

For exact existing commands and fields, use compiler-free export and PLA contract. The broader platinum new/build/run/doctor --gui project tool is specified in the project utility document; not every proposed command is a shipped binary in this checkout. Never present the provisional syntax as a required installed user command until its provider is built and accepted.

When Rust is appropriate

Use a native module when the public Lua/service API cannot express a required core extension. Keep it small: typed bounded inputs, explicit capabilities, asynchronous expensive work and a reviewed serialization/ABI boundary. The GUI remains a consumer of its result. Do not put secret keys or a privileged operation directly into an untrusted panel callback.

See the GUI native integration tutorial, module guide and native-module specification. The reference is extracted from public source; feature gates and platform/provider availability still apply.

Keep documentation with the code

Public Rust items use /// comments and module guides use //!. Put purpose, input constraints, results/events, errors, authority/lifetime and an example near the implementation. Lua bindings should carry the same information in the binding catalog, including their actual Event Table/native counterpart where one exists. Do not infer a counterpart merely because names look similar.

Run Platinum Documentation after changes. It produces a bounded intermediate representation and escaped HTML, with explicit missing-prose/coverage reports. It does not replace a Rust compiler, typechecker, security review or runnable tutorial verification. Generated pages should be regenerated from source; hand-edit the source comments/curated inputs instead of patching output HTML.