@threenative/ui API

Generated from the engine's capability manifest: 6 functions. Each entry is the exported signature, what it is for, and a working example. Start with the package overview.

DebugOverlay

function · import { DebugOverlay } from "@threenative/ui"

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()

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

function · import { GameCanvas } from "@threenative/ui"

Mount a ThreeNative game in a React canvas.

function GameCanvas<TState extends Record<string, unknown>, TPhysics>(

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

function · import { UiLayer } from "@threenative/ui"

Render a game's UI so the same source runs on web and on every native target.

function UiLayer(

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

function · import { useGameState } from "@threenative/ui"

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;

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

function · import { useUiIntent } from "@threenative/ui"

Send a player action from the UI back to the game.

function useUiIntent(): (intent: string, payload?: unknown) => void

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

function · import { useUiState } from "@threenative/ui"

Read the game's published state from a UI that may be in another process.

function useUiState<TState extends object>(): TState | undefined;

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