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, queues translated platform values through exported functions, 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.

Module contents

Constructors

ConstructorDescription
newSessionCreates a configurable session without starting the application.

Types

TypeKindDescription
SessionrecordHost-owned state rooted by one Nupp managed handle.

Functions

FunctionKindDescription
applyWindowStatefunctionApplies a complete state acknowledgement after processing commands.
attachWindowfunctionAttaches the Rust-created window with a complete initial state.
captureResultfunctionDelivers one completed frame readback to its requester.
crashedfunctionReturns the first guarded application failure, if one exists.
createfunctionCreates one blank application session for the Rust host.
createWithPluginfunctionCreates an application session around a game-owned installation callback.
detachWindowfunctionDetaches the OS window after the host destroys it.
imageCommandResultfunctionRecords the backend's outcome for one drained image command.
initfunctionStarts initialization and parks asynchronous startup work between host turns.
iteratefunctionStarts one frame or polls the frame already parked on asynchronous work.
nextCapturefunctionConsumes the next explicit frame capture request.
nextImageCommandfunctionReturns and consumes the next pending image residency command.
nextModelUploadfunctionDrains one pending model upload for the native renderer.
nextWindowCommandfunctionReturns and consumes the next pending window command.
pushClosefunctionQueues a close request for the application window.
pushFocusfunctionQueues a window focus transition.
pushKeyfunctionQueues a physical and logical keyboard transition.
pushPointerButtonfunctionQueues a pointer button transition.
pushPointerMovefunctionQueues an absolute pointer position and relative delta.
pushQuitfunctionQueues a process quit event.
pushResizefunctionQueues a logical and physical window size observation.
pushTextfunctionQueues committed input-method text.
pushTouchfunctionQueues one finger's transition or movement on a touch surface.
pushWheelfunctionQueues normalized wheel movement.
renderPacketfunctionExtracts the current renderable world into one versioned byte packet.
setSuspendedfunctionChanges whether host turns advance simulation.
shutdownfunctionRuns application shutdown once.
windowCommandFailedfunctionReports one rejected command to the game-facing window.

Constructors#

newSessionconstructor#

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

Creates a configurable session without starting the application.

Arguments

NameTypeDescription
configapplication.Config?

the application settings, including world timing and optional MCP port.

Returns

TypeDescription
Session

the session a component's constructor gives the Rust host.

Raises

  • when application configuration is invalid.

Types#

Sessionrecord#

record Session
    app: application.Application
end

Host-owned state rooted by one Nupp managed handle.

Fields

app#
app: application.Application

Functions#

applyWindowStatefunction#

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

NameTypeDescription
exclusive sessionSession
idinteger
titlestring
widthinteger
heightinteger
pixelWidthinteger
pixelHeightinteger
scaleFactornumber
xinteger
yinteger
focusedboolean
visibleboolean
minimizedboolean
maximizedboolean
fullscreenboolean
occludedboolean
resizableboolean
cursorVisibleboolean
cursorGrabstring

Returns

TypeDescription
nil

attachWindowfunction#

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

NameTypeDescription
exclusive sessionSession
idinteger
titlestring
widthinteger
heightinteger
pixelWidthinteger
pixelHeightinteger
scaleFactornumber
xinteger
yinteger
focusedboolean
visibleboolean
minimizedboolean
maximizedboolean
fullscreenboolean
occludedboolean
resizableboolean
cursorVisibleboolean
cursorGrabstring

Returns

TypeDescription
nil

captureResultfunction#

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

NameTypeDescription
exclusive sessionSession
idinteger
widthinteger
heightinteger
rgbastring
pngstring
reasonstring?

Returns

TypeDescription
nil

crashedfunction#

function crashed(borrows session: Session): string?

Returns the first guarded application failure, if one exists.

Arguments

NameTypeDescription
borrows sessionSession

Returns

TypeDescription
string?

createfunction#

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

Creates one blank application session for the Rust host.

Arguments

NameTypeDescription
titlestring?

the desktop title, defaulting to tecs

widthinteger?

the positive initial logical width, defaulting to 1280

heightinteger?

the positive initial logical height, defaulting to 720

debugboolean?

whether guarded application failures may be cleared

maxFramesinteger?

an optional positive frame limit for host smoke runs

Returns

TypeDescription
Session

the session the embedding host keeps as a managed handle

createWithPluginfunction#

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

NameTypeDescription
pluginapplication.Plugin

the game installation callback

titlestring?

the desktop title, defaulting to tecs

widthinteger?

the positive initial logical width, defaulting to 1280

heightinteger?

the positive initial logical height, defaulting to 720

debugboolean?

whether guarded application failures may be cleared

maxFramesinteger?

an optional positive frame limit for host smoke runs

Returns

TypeDescription
Session

the session the embedding host keeps as a managed handle

detachWindowfunction#

function detachWindow(exclusive session: Session): nil

Detaches the OS window after the host destroys it.

Arguments

NameTypeDescription
exclusive sessionSession

Returns

TypeDescription
nil

imageCommandResultfunction#

function imageCommandResult(exclusive session: Session, image: integer, serial: integer, ok: boolean, reason: string?): nil

Records the backend's outcome for one drained image command.

Arguments

NameTypeDescription
exclusive sessionSession

the host session that drained the command

imageinteger

the image id the command named

serialinteger

the command serial the host applied

okboolean

whether the backend accepted the command

reasonstring?

the non-empty host failure, required when ok is false

Returns

TypeDescription
nil

initfunction#

function init(exclusive session: Session): boolean

Starts initialization and parks asynchronous startup work between host turns.

Arguments

NameTypeDescription
exclusive sessionSession

the application session to initialize.

Returns

TypeDescription
boolean

true while the host may continue driving startup or diagnostics.

iteratefunction#

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

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

Arguments

NameTypeDescription
exclusive sessionSession
dtnumber

Returns

TypeDescription
framepump.State

parked, continue, or stopped

nextCapturefunction#

function nextCapture(exclusive session: Session): integer

Consumes the next explicit frame capture request.

Arguments

NameTypeDescription
exclusive sessionSession

Returns

TypeDescription
integer

nextImageCommandfunction#

function nextImageCommand(exclusive session: Session): string?, integer?, integer?, integer?, integer?, integer?, string?, string?, integer?, integer?, integer?

Returns and consumes the next pending image residency command.

The result is a scalar tagged tuple for the managed embedding ABI. kind selects upload, release, or material-map association. A release leaves every field after image nil. pixels carries eight-bit RGBA texels with unassociated alpha, four bytes per texel, in rows running top to bottom.

Arguments

NameTypeDescription
exclusive sessionSession

the host session draining the process-wide image registry

Returns

TypeDescription
string?

the command kind, the serial, the image id, the width, the height, the sampler index, pixel format, texel bytes, normal, emission and ORM IDs

integer?
integer?
integer?
integer?
integer?
string?
string?
integer?
integer?
integer?

nextModelUploadfunction#

function nextModelUpload(): integer, string

Drains one pending model upload for the native renderer.

Returns

TypeDescription
integer

The model ID and geometry packet, or zero and an empty string.

string

nextWindowCommandfunction#

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

NameTypeDescription
exclusive sessionSession

Returns

TypeDescription
string?
integer?
string?
number?
number?
boolean?

pushClosefunction#

function pushClose(exclusive session: Session, timestamp: number, sequence: integer): nil

Queues a close request for the application window.

Arguments

NameTypeDescription
exclusive sessionSession
timestampnumber
sequenceinteger

Returns

TypeDescription
nil

pushFocusfunction#

function pushFocus(exclusive session: Session, focused: boolean, timestamp: number, sequence: integer): nil

Queues a window focus transition.

Arguments

NameTypeDescription
exclusive sessionSession
focusedboolean
timestampnumber
sequenceinteger

Returns

TypeDescription
nil

pushKeyfunction#

function pushKey(exclusive session: Session, down: boolean, physicalKey: string, logicalKey: string?, text: string?, modifiers: integer, repeated: boolean, timestamp: number, sequence: integer): nil

Queues a physical and logical keyboard transition.

Arguments

NameTypeDescription
exclusive sessionSession
downboolean
physicalKeystring
logicalKeystring?
textstring?
modifiersinteger
repeatedboolean
timestampnumber
sequenceinteger

Returns

TypeDescription
nil

pushPointerButtonfunction#

function pushPointerButton(exclusive session: Session, down: boolean, button: integer, x: number, y: number, timestamp: number, sequence: integer): nil

Queues a pointer button transition.

Arguments

NameTypeDescription
exclusive sessionSession
downboolean
buttoninteger
xnumber
ynumber
timestampnumber
sequenceinteger

Returns

TypeDescription
nil

pushPointerMovefunction#

function pushPointerMove(exclusive session: Session, x: number, y: number, dx: number, dy: number, timestamp: number, sequence: integer): nil

Queues an absolute pointer position and relative delta.

Arguments

NameTypeDescription
exclusive sessionSession
xnumber
ynumber
dxnumber
dynumber
timestampnumber
sequenceinteger

Returns

TypeDescription
nil

pushQuitfunction#

function pushQuit(exclusive session: Session, timestamp: number, sequence: integer): nil

Queues a process quit event.

Arguments

NameTypeDescription
exclusive sessionSession
timestampnumber
sequenceinteger

Returns

TypeDescription
nil

pushResizefunction#

function pushResize(exclusive session: Session, scaleChanged: boolean, width: integer, height: integer, pixelWidth: integer, pixelHeight: integer, scaleFactor: number, timestamp: number, sequence: integer): nil

Queues a logical and physical window size observation.

Arguments

NameTypeDescription
exclusive sessionSession
scaleChangedboolean
widthinteger
heightinteger
pixelWidthinteger
pixelHeightinteger
scaleFactornumber
timestampnumber
sequenceinteger

Returns

TypeDescription
nil

pushTextfunction#

function pushText(exclusive session: Session, text: string, timestamp: number, sequence: integer): nil

Queues committed input-method text.

Arguments

NameTypeDescription
exclusive sessionSession
textstring
timestampnumber
sequenceinteger

Returns

TypeDescription
nil

pushTouchfunction#

function pushTouch(exclusive session: Session, phase: string, touchDevice: string, finger: string, x: number, y: number, normalX: number, normalY: number, pressure: number, dx: number, dy: number, timestamp: number, sequence: integer): nil

Queues one finger's transition or movement on a touch surface.

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.

Arguments

NameTypeDescription
exclusive sessionSession

the host session queuing the event

phasestring

one of fingerDown, fingerMotion, fingerUp or fingerCanceled

touchDevicestring

the touch surface's opaque identity

fingerstring

the finger's opaque identity on that surface

xnumber

the position in logical window coordinates

ynumber

the position in logical window coordinates

normalXnumber

the position across the surface, from zero to one

normalYnumber

the position down the surface, from zero to one

pressurenumber

the reported pressure from zero to one, and zero when the surface does not measure it

dxnumber

the movement since this finger's previous event

dynumber

the movement since this finger's previous event

timestampnumber

the host time the platform reported

sequenceinteger

the host's ordering number for this batch

Returns

TypeDescription
nil

Raises

  • when the phase is not one of the four kinds

pushWheelfunction#

function pushWheel(exclusive session: Session, wheelX: number, wheelY: number, ticksX: integer, ticksY: integer, x: number, y: number, timestamp: number, sequence: integer): nil

Queues normalized wheel movement.

Arguments

NameTypeDescription
exclusive sessionSession
wheelXnumber
wheelYnumber
ticksXinteger
ticksYinteger
xnumber
ynumber
timestampnumber
sequenceinteger

Returns

TypeDescription
nil

renderPacketfunction#

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

NameTypeDescription
exclusive sessionSession
residentRevisioninteger?

The host's resident instance generation, or nil for an independent full snapshot.

Returns

TypeDescription
string

the packet consumed by the Rust renderer after a completed frame

setSuspendedfunction#

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

Changes whether host turns advance simulation.

Arguments

NameTypeDescription
exclusive sessionSession
suspendedboolean

Returns

TypeDescription
nil

shutdownfunction#

function shutdown(exclusive session: Session): boolean

Runs application shutdown once.

Arguments

NameTypeDescription
exclusive sessionSession

Returns

TypeDescription
boolean

windowCommandFailedfunction#

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

Reports one rejected command to the game-facing window.

Arguments

NameTypeDescription
exclusive sessionSession
serialinteger
reasonstring

Returns

TypeDescription
nil