API by package
@threenative/ui API
Every public function and class in @threenative/ui. React bindings for mounting a ThreeNative game and reading throttled state.
On this page
Generated from the engine's capability manifest: 7 functions. Each entry is the exported signature, what it is for, and a working example. Start with the package overview.
DebugOverlay
Show framework diagnostics while developing a game. Backtick opens it; the Entities tab lists registered entity fields, and the Geometry tab captures one frame and ranks the objects that submitted its triangles beside their projected size on screen.
function DebugOverlay()Needs
- npm i @threenative/ui
Use it to
- display runtime and playtest diagnostics in a React HUD
- inspect a game without changing its scene
- find out which scene object is submitting the frame's triangles
- tell a cheap foreground character from an expensive distant prop
Example
<DebugOverlay />Good to know
- the Geometry tab captures only on an explicit press; nothing is collected while idle
- per-object numbers are measured submissions reconciled against the frame's own pass totals, and the remainder is reported rather than hidden
GameCanvas
Mount a ThreeNative game in a React canvas.
function GameCanvas<TState extends Record<string, unknown>, TPhysics>(Needs
- npm i @threenative/ui
Use it to
- add a game viewport to a React application
- connect a game canvas to the web UI shell
Example
<GameCanvas game={game} />Good to know
- keep the portable game entry free of React DOM code
UiLayer
Render a game's UI so the same source runs on web and on every native target.
function UiLayer(Needs
- npm i @threenative/ui
Use it to
- write one HUD that looks the same on the web build and on a phone
- mount a React UI over the game surface on Android or iOS
Example
<UiLayer><Hud /></UiLayer>Good to know
- mark every control the player touches with data-tn-interactive
useGameState
Read the game's coalesced frame snapshot from React.
function useGameState<TState extends Record<string, unknown>, TPhysics, TSelected>( game: IGame<TState, TPhysics>, selector: GameSelector<TState, TSelected>, ): TSelected;Needs
- npm i @threenative/ui
Use it to
- bind a HUD component to game state
- select a slice of state for a React panel
Example
const score = useGameState(game, (state) => state.score);Good to know
- use this hook only from the web UI entry
useUiIntent
Send a player action from the UI back to the game.
function useUiIntent(): (intent: string, payload?: unknown) => voidNeeds
- npm i @threenative/ui
Use it to
- wire a Restart button in a HUD to the running game
- pause a game from a menu rendered over its surface
Example
const send = useUiIntent(); send("restart");Good to know
- the game decides what each intent name means; it may ignore one
useUiState
Read the game's published state from a UI that may be in another process.
function useUiState<TState extends object>(): TState | undefined;Needs
- npm i @threenative/ui
Use it to
- bind a HUD to game state on web and native alike
- show score or health in a UI rendered over the game surface
Example
const score = useUiState<GameState, number>((state) => state.score);Good to know
- returns undefined until the game publishes its first state and while the loading cover is up
useUiStateDuringStartup
Read the game's published state while the loading cover is still up, for a UI that draws its own loading screen.
function useUiStateDuringStartup<TState extends object>(options:Needs
- npm i @threenative/ui
Use it to
- draw a staged loading overlay from the startup progress the game publishes
Example
const loading = useUiStateDuringStartup<GameState, number>({ reason: "staged loading overlay" }, (state) => state.loading.progress);Good to know
- needs a non-empty reason, reported once as TN_UI_STARTUP_OVERRIDE; every other HUD uses useUiState