`tecs.host`

Managed-call bridge between the Rust application host and Nupp game state.

This module keeps the embedding ABI scalar. Rust holds a managed Session handle and asks for one frame at a time. Records remain inside Nupp and no Lua stack layout or collector address becomes part of the host contract.

Translated platform input crosses on the nupp.host channel rather than through exports. The host pushes each observation on a tecs.input.* kind, and the session routes every kind to its input bus as the matching record below, whose fields are the pushed values in order. A route delivers at the start of the next frame, or while a frame is parked, and the session queues the platform event for the frame after it. The kinds are a compatibility surface between this module and the host.

Image residency commands cross the same channel the other way. A frame that queued uploads, releases or material maps asks the host to apply each one on a tecs.image.* call, in the order it queued them, and parks until the host answers from its loop. The answer completes the command in tecs.gfx.images, so the frame that queued an upload finishes with it resident or failed, and the packet the host extracts next already says so.

Module contents

Types

Type	Kind	Description
`CloseInput`	record	A close request the host pushed on tecs.input.close.
`FocusInput`	record	A focus transition the host pushed on tecs.input.focus.
`KeyInput`	record	A keyboard transition the host pushed on tecs.input.key.
`PointerButtonInput`	record	A pointer button transition the host pushed on tecs.input.pointer-button.
`PointerMoveInput`	record	An absolute pointer position and relative delta the host pushed on tecs.input.pointer-move.
`ResizeInput`	record	A size observation the host pushed on tecs.input.resize.
`Session`	record	Host-owned state rooted by one Nupp managed handle.
`TextInput`	record	Committed input-method text the host pushed on tecs.input.text.
`TouchInput`	record	One finger's transition or movement the host pushed on tecs.input.touch.
`WheelInput`	record	Normalized wheel movement the host pushed on tecs.input.wheel.

Functions

Function	Kind	Description
`applyWindowState`	function	Applies a complete state acknowledgement after processing commands.
`attachWindow`	function	Attaches the Rust-created window with a complete initial state.
`captureResult`	function	Delivers one completed frame readback to its requester.
`crashed`	function	Returns the first guarded application failure, if one exists.
`create`	function	Creates one blank application session for the Rust host.
`createWithPlugin`	function	Creates an application session around a game-owned installation callback.
`detachWindow`	function	Detaches the OS window after the host destroys it.
`init`	function	Starts initialization and parks asynchronous startup work between host turns.
`iterate`	function	Starts one frame or polls the frame already parked on asynchronous work.
`newSession`	function	Creates a configurable session without starting the application.
`nextCapture`	function	Consumes the next explicit frame capture request.
`nextModelUpload`	function	Drains one pending model upload for the native renderer.
`nextWindowCommand`	function	Returns and consumes the next pending window command.
`renderPacket`	function	Extracts the current renderable world into one versioned byte packet.
`setSuspended`	function	Changes whether host turns advance simulation.
`shutdown`	function	Runs application shutdown once.
`windowCommandFailed`	function	Reports one rejected command to the game-facing window.

Values

Value	Kind	Description
`INPUT_ADDRESS`	variable	The address every input route delivers at.

Types#

`CloseInput`record#

record CloseInput ...

@derive(events.Event)

A close request the host pushed on tecs.input.close.

Members

Name	Kind	Description
`timestamp`	field
`sequence`	field

`timestamp`field#

timestamp: number

`sequence`field#

sequence: integer

`FocusInput`record#

record FocusInput ...

@derive(events.Event)

A focus transition the host pushed on tecs.input.focus.

Members

Name	Kind	Description
`focused`	field
`timestamp`	field
`sequence`	field

`focused`field#

focused: boolean

`timestamp`field#

timestamp: number

`sequence`field#

sequence: integer

`KeyInput`record#

record KeyInput ...

@derive(events.Event)

A keyboard transition the host pushed on tecs.input.key.

Members

Name	Kind	Description
`down`	field
`physicalKey`	field
`logicalKey`	field
`text`	field
`modifiers`	field
`repeated`	field
`timestamp`	field
`sequence`	field

`down`field#

down: boolean

`physicalKey`field#

physicalKey: string

`logicalKey`field#

logicalKey: string?

`text`field#

text: string?

`modifiers`field#

modifiers: integer

`repeated`field#

repeated: boolean

`timestamp`field#

timestamp: number

`sequence`field#

sequence: integer

`PointerButtonInput`record#

record PointerButtonInput ...

@derive(events.Event)

A pointer button transition the host pushed on tecs.input.pointer-button.

Members

Name	Kind	Description
`down`	field
`button`	field
`x`	field
`y`	field
`timestamp`	field
`sequence`	field

`down`field#

down: boolean

`button`field#

button: integer

`x`field#

x: number

`y`field#

y: number

`timestamp`field#

timestamp: number

`sequence`field#

sequence: integer

`PointerMoveInput`record#

record PointerMoveInput ...

@derive(events.Event)

An absolute pointer position and relative delta the host pushed on tecs.input.pointer-move.

Members

Name	Kind	Description
`x`	field
`y`	field
`dx`	field
`dy`	field
`timestamp`	field
`sequence`	field

`x`field#

x: number

`y`field#

y: number

`dx`field#

dx: number

`dy`field#

dy: number

`timestamp`field#

timestamp: number

`sequence`field#

sequence: integer

`ResizeInput`record#

record ResizeInput ...

@derive(events.Event)

A size observation the host pushed on tecs.input.resize.

Members

Name	Kind	Description
`scaleChanged`	field	Read-only.
`width`	field
`height`	field
`pixelWidth`	field
`pixelHeight`	field
`scaleFactor`	field
`timestamp`	field
`sequence`	field

`scaleChanged`field#

scaleChanged: boolean

Read-only. Reports whether the scale factor changed rather than only the size.

`width`field#

width: integer

`height`field#

height: integer

`pixelWidth`field#

pixelWidth: integer

`pixelHeight`field#

pixelHeight: integer

`scaleFactor`field#

scaleFactor: number

`timestamp`field#

timestamp: number

`sequence`field#

sequence: integer

`Session`record#

record Session ...

Host-owned state rooted by one Nupp managed handle.

Members

Name	Kind	Description
`app`	field
`input`	field	Engine-owned.
`hosted`	field
`routes`	field
`events`	field
`commands`	field
`commandIndex`	field
`pump`	field
`extractor`	field
`views`	field

`app`field#

app: application.Application

`input`field#

input: events.MessageBus<integer>

Engine-owned. Receives the host's pushed input as the records above at INPUT_ADDRESS. Public so a test can emit on it in place of a host; game code should ignore it.

`hosted`field#

hosted: boolean

@private

`routes`field#

routes: {nupphost.Route}

@private

`events`field#

events: {platformevents.Event}

@private

`commands`field#

commands: {window.Command}

@private

`commandIndex`field#

commandIndex: integer

@private

`pump`field#

pump: hostpump.Pump

@private

`extractor`field#

extractor: framepacket.Extractor

@private

`views`field#

views: viewpacket.Collector

@private

`TextInput`record#

record TextInput ...

@derive(events.Event)

Committed input-method text the host pushed on tecs.input.text.

Members

Name	Kind	Description
`text`	field
`timestamp`	field
`sequence`	field

`text`field#

text: string

`timestamp`field#

timestamp: number

`sequence`field#

sequence: integer

`TouchInput`record#

record TouchInput ...

@derive(events.Event)

One finger's transition or movement the host pushed on tecs.input.touch.

x and y are in the window's logical coordinates and normalX and normalY run from zero to one across the surface. touchDevice and finger are strings rather than numbers because both are 64-bit platform identities that a Lua number would round together.

Members

Name	Kind	Description
`phase`	field	Read-only.
`touchDevice`	field
`finger`	field
`x`	field
`y`	field
`normalX`	field
`normalY`	field
`pressure`	field
`dx`	field
`dy`	field
`timestamp`	field
`sequence`	field

`phase`field#

phase: string

Read-only. Names one of fingerDown, fingerMotion, fingerUp or fingerCanceled.

`touchDevice`field#

touchDevice: string

`finger`field#

finger: string

`x`field#

x: number

`y`field#

y: number

`normalX`field#

normalX: number

`normalY`field#

normalY: number

`pressure`field#

pressure: number

`dx`field#

dx: number

`dy`field#

dy: number

`timestamp`field#

timestamp: number

`sequence`field#

sequence: integer

`WheelInput`record#

record WheelInput ...

@derive(events.Event)

Normalized wheel movement the host pushed on tecs.input.wheel.

Members

Name	Kind	Description
`wheelX`	field
`wheelY`	field
`ticksX`	field
`ticksY`	field
`x`	field
`y`	field
`timestamp`	field
`sequence`	field

`wheelX`field#

wheelX: number

`wheelY`field#

wheelY: number

`ticksX`field#

ticksX: integer

`ticksY`field#

ticksY: integer

`x`field#

x: number

`y`field#

y: number

`timestamp`field#

timestamp: number

`sequence`field#

sequence: integer

Functions#

`applyWindowState`function#

function applyWindowState(exclusive session: Session, id: integer, title: string, width: integer, height: integer, pixelWidth: integer, pixelHeight: integer, scaleFactor: number, x: integer, y: integer, focused: boolean, visible: boolean, minimized: boolean, maximized: boolean, fullscreen: boolean, occluded: boolean, resizable: boolean, cursorVisible: boolean, cursorGrab: string): nil

Applies a complete state acknowledgement after processing commands.

Arguments

Name	Type	Description
`exclusive session`	`Session`
`id`	`integer`
`title`	`string`
`width`	`integer`
`height`	`integer`
`pixelWidth`	`integer`
`pixelHeight`	`integer`
`scaleFactor`	`number`
`x`	`integer`
`y`	`integer`
`focused`	`boolean`
`visible`	`boolean`
`minimized`	`boolean`
`maximized`	`boolean`
`fullscreen`	`boolean`
`occluded`	`boolean`
`resizable`	`boolean`
`cursorVisible`	`boolean`
`cursorGrab`	`string`

Returns

Type	Description
`nil`

`attachWindow`function#

function attachWindow(exclusive session: Session, id: integer, title: string, width: integer, height: integer, pixelWidth: integer, pixelHeight: integer, scaleFactor: number, x: integer, y: integer, focused: boolean, visible: boolean, minimized: boolean, maximized: boolean, fullscreen: boolean, occluded: boolean, resizable: boolean, cursorVisible: boolean, cursorGrab: string): nil

Attaches the Rust-created window with a complete initial state.

Arguments

Name	Type	Description
`exclusive session`	`Session`
`id`	`integer`
`title`	`string`
`width`	`integer`
`height`	`integer`
`pixelWidth`	`integer`
`pixelHeight`	`integer`
`scaleFactor`	`number`
`x`	`integer`
`y`	`integer`
`focused`	`boolean`
`visible`	`boolean`
`minimized`	`boolean`
`maximized`	`boolean`
`fullscreen`	`boolean`
`occluded`	`boolean`
`resizable`	`boolean`
`cursorVisible`	`boolean`
`cursorGrab`	`string`

Returns

Type	Description
`nil`

`captureResult`function#

function captureResult(exclusive session: Session, id: integer, width: integer, height: integer, rgba: string, png: string, reason: string?): nil

Delivers one completed frame readback to its requester.

Arguments

Name	Type	Description
`exclusive session`	`Session`
`id`	`integer`
`width`	`integer`
`height`	`integer`
`rgba`	`string`
`png`	`string`
`reason`	`string?`

Returns

Type	Description
`nil`

`crashed`function#

function crashed(borrows session: Session): string?

Returns the first guarded application failure, if one exists.

Arguments

Name	Type	Description
`borrows session`	`Session`

Returns

Type	Description
`string?`

`create`function#

function create(title: string?, width: integer?, height: integer?, debug: boolean?, maxFrames: integer?): Session

Creates one blank application session for the Rust host.

Arguments

Name	Type	Description
`title`	`string?`	the desktop title, defaulting to `tecs`
`width`	`integer?`	the positive initial logical width, defaulting to 1280
`height`	`integer?`	the positive initial logical height, defaulting to 720
`debug`	`boolean?`	whether guarded application failures may be cleared
`maxFrames`	`integer?`	an optional positive frame limit for host smoke runs

Returns

Type	Description
`Session`	the session the embedding host keeps as a managed handle

`createWithPlugin`function#

function createWithPlugin(plugin: application.Plugin, title: string?, width: integer?, height: integer?, debug: boolean?, maxFrames: integer?): Session

Creates an application session around a game-owned installation callback.

A game component exports a function with the managed create signature and delegates here with its statically imported plugin. Rust selects that export with --entry, so the host never dynamically requires game code.

Arguments

Name	Type	Description
`plugin`	`application.Plugin`	the game installation callback
`title`	`string?`	the desktop title, defaulting to `tecs`
`width`	`integer?`	the positive initial logical width, defaulting to 1280
`height`	`integer?`	the positive initial logical height, defaulting to 720
`debug`	`boolean?`	whether guarded application failures may be cleared
`maxFrames`	`integer?`	an optional positive frame limit for host smoke runs

Returns

Type	Description
`Session`	the session the embedding host keeps as a managed handle

`detachWindow`function#

function detachWindow(exclusive session: Session): nil

Detaches the OS window after the host destroys it.

Arguments

Name	Type	Description
`exclusive session`	`Session`

Returns

Type	Description
`nil`

`init`function#

function init(exclusive session: Session): boolean

Starts initialization and parks asynchronous startup work between host turns.

Arguments

Name	Type	Description
`exclusive session`	`Session`	the application session to initialize.

Returns

Type	Description
`boolean`	true while the host may continue driving startup or diagnostics.

`iterate`function#

function iterate(exclusive session: Session, dt: number): hostpump.State

Starts one frame or polls the frame already parked on asynchronous work.

Arguments

Name	Type	Description
`exclusive session`	`Session`
`dt`	`number`

Returns

Type	Description
`hostpump.State`	`parked`, `continue`, or `stopped`

`newSession`function#

function newSession(config: application.Config?): Session

Creates a configurable session without starting the application.

Under an embedding host the session routes the host's tecs.input.* pushes to its input bus. Without one, as in a test, nothing is routed and input arrives only by emitting on that bus.

Arguments

Name	Type	Description
`config`	`application.Config?`	the application settings, including world timing and optional MCP port.

Returns

Type	Description
`Session`	the session a component's constructor gives the Rust host.

Raises

Type	Condition
`string`	when application configuration is invalid.

`nextCapture`function#

function nextCapture(exclusive session: Session): integer

Consumes the next explicit frame capture request.

Arguments

Name	Type	Description
`exclusive session`	`Session`

Returns

Type	Description
`integer`

`nextModelUpload`function#

function nextModelUpload(): integer, string

Drains one pending model upload for the native renderer.

Returns

Type	Description
`integer`	The model ID and geometry packet, or zero and an empty string.
`string`

`nextWindowCommand`function#

function nextWindowCommand(exclusive session: Session): string?, integer?, string?, number?, number?, boolean?

Returns and consumes the next pending window command.

The result is a scalar tagged tuple for the managed embedding ABI. text carries a title or cursor mode, x and y carry size or position, and flag carries a boolean setter. Fields unused by a kind are nil.

Arguments

Name	Type	Description
`exclusive session`	`Session`

Returns

Type	Description
`string?`
`integer?`
`string?`
`number?`
`number?`
`boolean?`

`renderPacket`function#

function renderPacket(exclusive session: Session, residentRevision: integer?): string

Extracts the current renderable world into one versioned byte packet.

The viewport is the window's physical drawable size rather than its logical size, because the camera projects into target pixels and the swapchain the packet is drawn into is that size on every display.

Arguments

Name	Type	Description
`exclusive session`	`Session`
`residentRevision`	`integer?`	The host's resident instance generation, or nil for an independent full snapshot.

Returns

Type	Description
`string`	the packet consumed by the Rust renderer after a completed frame

`setSuspended`function#

function setSuspended(exclusive session: Session, suspended: boolean): nil

Changes whether host turns advance simulation.

Arguments

Name	Type	Description
`exclusive session`	`Session`
`suspended`	`boolean`

Returns

Type	Description
`nil`

`shutdown`function#

function shutdown(exclusive session: Session): boolean

Runs application shutdown once.

Arguments

Name	Type	Description
`exclusive session`	`Session`

Returns

Type	Description
`boolean`

`windowCommandFailed`function#

function windowCommandFailed(exclusive session: Session, serial: integer, reason: string): nil

Reports one rejected command to the game-facing window.

Arguments

Name	Type	Description
`exclusive session`	`Session`
`serial`	`integer`
`reason`	`string`

Returns

Type	Description
`nil`

Values#

`INPUT_ADDRESS`variable#

const INPUT_ADDRESS: integer

The address every input route delivers at. The host drives one window.

tecs.host

Module contents

Types

Functions

Values

Types#

CloseInputrecord#

Members

timestampfield#

sequencefield#

FocusInputrecord#

Members

focusedfield#

timestampfield#

sequencefield#

KeyInputrecord#

Members

downfield#

physicalKeyfield#

logicalKeyfield#

textfield#

modifiersfield#

repeatedfield#

timestampfield#

sequencefield#

PointerButtonInputrecord#

Members

downfield#

buttonfield#

xfield#

yfield#

timestampfield#

sequencefield#

PointerMoveInputrecord#

Members

xfield#

yfield#

dxfield#

dyfield#

timestampfield#

sequencefield#

ResizeInputrecord#

Members

scaleChangedfield#

widthfield#

heightfield#

pixelWidthfield#

pixelHeightfield#

scaleFactorfield#

timestampfield#

sequencefield#

Sessionrecord#

Members

appfield#

inputfield#

hostedfield#

routesfield#

eventsfield#

commandsfield#

commandIndexfield#

pumpfield#

extractorfield#

viewsfield#

TextInputrecord#

Members

textfield#

timestampfield#

sequencefield#

TouchInputrecord#

Members

phasefield#

touchDevicefield#

fingerfield#

xfield#

yfield#

normalXfield#

normalYfield#

pressurefield#

dxfield#

dyfield#

`tecs.host`

`CloseInput`record#

`timestamp`field#

`sequence`field#

`FocusInput`record#

`focused`field#

`timestamp`field#

`sequence`field#

`KeyInput`record#

`down`field#

`physicalKey`field#

`logicalKey`field#

`text`field#

`modifiers`field#

`repeated`field#

`timestamp`field#

`sequence`field#

`PointerButtonInput`record#

`down`field#

`button`field#

`x`field#

`y`field#

`timestamp`field#

`sequence`field#

`PointerMoveInput`record#

`x`field#

`y`field#

`dx`field#

`dy`field#

`timestamp`field#

`sequence`field#

`ResizeInput`record#

`scaleChanged`field#

`width`field#

`height`field#

`pixelWidth`field#

`pixelHeight`field#

`scaleFactor`field#

`timestamp`field#

`sequence`field#

`Session`record#

`app`field#

`input`field#

`hosted`field#

`routes`field#

`events`field#

`commands`field#

`commandIndex`field#

`pump`field#

`extractor`field#

`views`field#

`TextInput`record#

`text`field#

`timestamp`field#

`sequence`field#

`TouchInput`record#

`phase`field#

`touchDevice`field#

`finger`field#

`x`field#

`y`field#

`normalX`field#

`normalY`field#

`pressure`field#

`dx`field#

`dy`field#

`timestamp`field#

`sequence`field#

`WheelInput`record#

`wheelX`field#

`wheelY`field#

`ticksX`field#

`ticksY`field#

`x`field#

`y`field#

`timestamp`field#

`sequence`field#

`applyWindowState`function#

`attachWindow`function#

`captureResult`function#