<a id="tecs.host"></a>
# `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.

## Constructors

<a id="tecs.host.newSession"></a>
### `newSession` _constructor_

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

Creates a configurable session without starting the application.

#### 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

- when application configuration is invalid.

## Types

<a id="tecs.host.Session"></a>
### `Session` _record_

```nupp
record Session
    app: application.Application
end
```

Host-owned state rooted by one Nupp managed handle.

#### Fields

<a id="tecs.host.Session.app"></a>
##### `app`

```nupp
app: application.Application
```

## Functions

<a id="tecs.host.applyWindowState"></a>
### `applyWindowState` _function_

```nupp
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` |  |

<a id="tecs.host.attachWindow"></a>
### `attachWindow` _function_

```nupp
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` |  |

<a id="tecs.host.captureResult"></a>
### `captureResult` _function_

```nupp
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` |  |

<a id="tecs.host.crashed"></a>
### `crashed` _function_

```nupp
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?` |  |

<a id="tecs.host.create"></a>
### `create` _function_

```nupp
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 |

<a id="tecs.host.createWithPlugin"></a>
### `createWithPlugin` _function_

```nupp
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 |

<a id="tecs.host.detachWindow"></a>
### `detachWindow` _function_

```nupp
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` |  |

<a id="tecs.host.imageCommandResult"></a>
### `imageCommandResult` _function_

```nupp
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

| Name | Type | Description |
| --- | --- | --- |
| `exclusive session` | `Session` | the host session that drained the command |
| `image` | `integer` | the image id the command named |
| `serial` | `integer` | the command serial the host applied |
| `ok` | `boolean` | whether the backend accepted the command |
| `reason` | `string?` | the non-empty host failure, required when `ok` is false |

#### Returns

| Type | Description |
| --- | --- |
| `nil` |  |

<a id="tecs.host.init"></a>
### `init` _function_

```nupp
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. |

<a id="tecs.host.iterate"></a>
### `iterate` _function_

```nupp
function iterate(exclusive session: Session, dt: number): framepump.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 |
| --- | --- |
| `framepump.State` | `parked`, `continue`, or `stopped` |

<a id="tecs.host.nextCapture"></a>
### `nextCapture` _function_

```nupp
function nextCapture(exclusive session: Session): integer
```

Consumes the next explicit frame capture request.

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `exclusive session` | `Session` |  |

#### Returns

| Type | Description |
| --- | --- |
| `integer` |  |

<a id="tecs.host.nextImageCommand"></a>
### `nextImageCommand` _function_

```nupp
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

| Name | Type | Description |
| --- | --- | --- |
| `exclusive session` | `Session` | the host session draining the process-wide image registry |

#### Returns

| Type | Description |
| --- | --- |
| `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?` |  |

<a id="tecs.host.nextModelUpload"></a>
### `nextModelUpload` _function_

```nupp
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` |  |

<a id="tecs.host.nextWindowCommand"></a>
### `nextWindowCommand` _function_

```nupp
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?` |  |

<a id="tecs.host.pushClose"></a>
### `pushClose` _function_

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

Queues a close request for the application window.

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `exclusive session` | `Session` |  |
| `timestamp` | `number` |  |
| `sequence` | `integer` |  |

#### Returns

| Type | Description |
| --- | --- |
| `nil` |  |

<a id="tecs.host.pushFocus"></a>
### `pushFocus` _function_

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

Queues a window focus transition.

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `exclusive session` | `Session` |  |
| `focused` | `boolean` |  |
| `timestamp` | `number` |  |
| `sequence` | `integer` |  |

#### Returns

| Type | Description |
| --- | --- |
| `nil` |  |

<a id="tecs.host.pushKey"></a>
### `pushKey` _function_

```nupp
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

| Name | Type | Description |
| --- | --- | --- |
| `exclusive session` | `Session` |  |
| `down` | `boolean` |  |
| `physicalKey` | `string` |  |
| `logicalKey` | `string?` |  |
| `text` | `string?` |  |
| `modifiers` | `integer` |  |
| `repeated` | `boolean` |  |
| `timestamp` | `number` |  |
| `sequence` | `integer` |  |

#### Returns

| Type | Description |
| --- | --- |
| `nil` |  |

<a id="tecs.host.pushPointerButton"></a>
### `pushPointerButton` _function_

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

Queues a pointer button transition.

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `exclusive session` | `Session` |  |
| `down` | `boolean` |  |
| `button` | `integer` |  |
| `x` | `number` |  |
| `y` | `number` |  |
| `timestamp` | `number` |  |
| `sequence` | `integer` |  |

#### Returns

| Type | Description |
| --- | --- |
| `nil` |  |

<a id="tecs.host.pushPointerMove"></a>
### `pushPointerMove` _function_

```nupp
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

| Name | Type | Description |
| --- | --- | --- |
| `exclusive session` | `Session` |  |
| `x` | `number` |  |
| `y` | `number` |  |
| `dx` | `number` |  |
| `dy` | `number` |  |
| `timestamp` | `number` |  |
| `sequence` | `integer` |  |

#### Returns

| Type | Description |
| --- | --- |
| `nil` |  |

<a id="tecs.host.pushQuit"></a>
### `pushQuit` _function_

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

Queues a process quit event.

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `exclusive session` | `Session` |  |
| `timestamp` | `number` |  |
| `sequence` | `integer` |  |

#### Returns

| Type | Description |
| --- | --- |
| `nil` |  |

<a id="tecs.host.pushResize"></a>
### `pushResize` _function_

```nupp
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

| Name | Type | Description |
| --- | --- | --- |
| `exclusive session` | `Session` |  |
| `scaleChanged` | `boolean` |  |
| `width` | `integer` |  |
| `height` | `integer` |  |
| `pixelWidth` | `integer` |  |
| `pixelHeight` | `integer` |  |
| `scaleFactor` | `number` |  |
| `timestamp` | `number` |  |
| `sequence` | `integer` |  |

#### Returns

| Type | Description |
| --- | --- |
| `nil` |  |

<a id="tecs.host.pushText"></a>
### `pushText` _function_

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

Queues committed input-method text.

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `exclusive session` | `Session` |  |
| `text` | `string` |  |
| `timestamp` | `number` |  |
| `sequence` | `integer` |  |

#### Returns

| Type | Description |
| --- | --- |
| `nil` |  |

<a id="tecs.host.pushTouch"></a>
### `pushTouch` _function_

```nupp
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

| Name | Type | Description |
| --- | --- | --- |
| `exclusive session` | `Session` | the host session queuing the event |
| `phase` | `string` | one of `fingerDown`, `fingerMotion`, `fingerUp` or `fingerCanceled` |
| `touchDevice` | `string` | the touch surface's opaque identity |
| `finger` | `string` | the finger's opaque identity on that surface |
| `x` | `number` | the position in logical window coordinates |
| `y` | `number` | the position in logical window coordinates |
| `normalX` | `number` | the position across the surface, from zero to one |
| `normalY` | `number` | the position down the surface, from zero to one |
| `pressure` | `number` | the reported pressure from zero to one, and zero when the surface does not measure it |
| `dx` | `number` | the movement since this finger's previous event |
| `dy` | `number` | the movement since this finger's previous event |
| `timestamp` | `number` | the host time the platform reported |
| `sequence` | `integer` | the host's ordering number for this batch |

#### Returns

| Type | Description |
| --- | --- |
| `nil` |  |

#### Raises

- when the phase is not one of the four kinds

<a id="tecs.host.pushWheel"></a>
### `pushWheel` _function_

```nupp
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

| Name | Type | Description |
| --- | --- | --- |
| `exclusive session` | `Session` |  |
| `wheelX` | `number` |  |
| `wheelY` | `number` |  |
| `ticksX` | `integer` |  |
| `ticksY` | `integer` |  |
| `x` | `number` |  |
| `y` | `number` |  |
| `timestamp` | `number` |  |
| `sequence` | `integer` |  |

#### Returns

| Type | Description |
| --- | --- |
| `nil` |  |

<a id="tecs.host.renderPacket"></a>
### `renderPacket` _function_

```nupp
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 |

<a id="tecs.host.setSuspended"></a>
### `setSuspended` _function_

```nupp
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` |  |

<a id="tecs.host.shutdown"></a>
### `shutdown` _function_

```nupp
function shutdown(exclusive session: Session): boolean
```

Runs application shutdown once.

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `exclusive session` | `Session` |  |

#### Returns

| Type | Description |
| --- | --- |
| `boolean` |  |

<a id="tecs.host.windowCommandFailed"></a>
### `windowCommandFailed` _function_

```nupp
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` |  |