# tecs


## Module contents

### Submodules

| Submodule | Description |
| --- | --- |
| [`tecs.Application`](/modules/Application/) | The application lifecycle, entry plugin, frame, checkpoints, and crash state |
| [`tecs.assets`](/modules/assets/) | Coroutine-native byte, image, sound, and animated glTF loading with skins and morph targets |
| [`tecs.audio`](/modules/audio/) | Clips, voices, groups, limits, entity sounds, snapshots, and audio devices |
| [`tecs.data`](/modules/data/) | Typed stores, JSON, byte encodings, DEFLATE, text transcoding, UTF-8, UUIDs, hashes, and checksums |
| [`tecs.debug`](/modules/debug/) | Debugger commands declared once and projected as debug-server tools with input and output schemas |
| [`tecs.ecs`](/modules/ecs/) | Worlds, entities, components, systems, plugins, queries, archetypes, phases, and resources |
| [`tecs.events`](/modules/events/) | Typed event definitions and address-based message buses |
| [`tecs.gfx`](/modules/gfx/) | 2D and 3D cameras, render components, meshes, the GPU renderer, images, shadows, and text |
| [`tecs.input`](/modules/input/) | Gameplay input in three tiers behind a layer stack, with gamepads and standalone sensors |
| [`tecs.io`](/modules/io/) | Synchronous binary streams, cooperative sockets, HTTP, files, and external tools |
| [`tecs.log`](/modules/log/) | Named loggers, priority filtering, platform output, and JSON Lines files |
| [`tecs.math`](/modules/math/) | Angle wrapping and shortest turns, with two-dimensional geometry beneath them. |
| [`tecs.physics`](/modules/physics/) | Entity-first Rapier 2D rigid bodies, colliders, queries, contacts, sensors, and snapshots |
| [`tecs.platform`](/modules/platform/) | Platform events, operating-system services, time, and windows |
| [`tecs.regex`](/modules/regex/) | Compiled Rust regular expressions over Lua byte strings |
| [`tecs.sequence`](/modules/sequence/) | Snapshot-safe programs, waits, ownership, actions, and tween timelines |
| [`tecs.ui`](/modules/ui/) | Retained layout, clipping, scrolling, and interaction for composed UI entities |
| [`tecs.workers`](/modules/workers/) | Separate Lua states joined by serialized channels, whose results and call replies a system waits for without blocking the frame |

### Constructors

| Constructor | Description |
| --- | --- |
| [`newApplication`](/modules/#tecs.newApplication) | Builds the application an entry file returns. |

### Types

| Type | Kind | Description |
| --- | --- | --- |
| [`Closeable`](/modules/#tecs.Closeable) | <span class="tealdoc-kind-badge tealdoc-kind-interface">interface</span> | An owned value that releases its active lifetime explicitly. |
| [`Scope`](/modules/#tecs.Scope) | <span class="tealdoc-kind-badge tealdoc-kind-interface">interface</span> | Scope owns resources while preserving each concrete type. |

### Functions

| Function | Kind | Description |
| --- | --- | --- |
| [`batch`](/modules/#tecs.batch) | <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span> | Runs callbacks at the same time and returns their results in order. |
| [`scoped`](/modules/#tecs.scoped) | <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span> | Runs a callback inside a fresh named resource scope and JIT zone. |

### Values

| Value | Type | Description |
| --- | --- | --- |
| [`version`](/modules/#tecs.version) | `string` | Read-only. Version of this build. |

## Constructors

<a id="tecs.newApplication"></a>
### tecs.newApplication <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span>

Builds the application an entry file returns.

Not a function that runs until done: an entry file ends with
`return tecs.newApplication(config)` and the host drives it from there,
because a platform that never hands control back has no loop to block
in.



```teal
function tecs.newApplication(
    config: Application.Config
): Application
```

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `config` | [`Application.Config`](/modules/Application/#tecs.Application.Config) | Read here, so a field changed on the table afterwards is not seen. Nothing is opened yet: the window, the GPU device and the audio mixer are the host's to bring up on the first callback, which is what lets an entry file be loaded by a tool that never runs one. |

#### Returns

| Type | Description |
| --- | --- |
| [`Application`](/modules/Application/) | The application the host drives through its init, event, iterate and quit callbacks. Returning it is the whole contract; a game that calls into it itself is doing the host's job. |

## Types

<a id="tecs.Closeable"></a>
### tecs.Closeable <span class="tealdoc-kind-badge tealdoc-kind-interface">interface</span>

An owned value that releases its active lifetime explicitly.

`close` may report a delayed finalization failure. Every implementation
returns true on success. Its own contract defines whether repeated calls
are safe.


```teal
interface tecs.Closeable
    close: function(self): boolean, string
end
```

<a id="tecs.Closeable.close"></a>
#### tecs.Closeable:close <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Releases the value's active lifetime.



```teal
function tecs.Closeable.close(self): boolean, string
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Closeable` | The value to close. |

##### Returns

| Type | Description |
| --- | --- |
| `boolean` | Returns true when finalization succeeds. |
| `string` | Returns a finalization reason when the first return is false. |

#### Examples

```teal
local destination <const> = tecs.io.newFileStream("save.bin")
local writer <const> = assert(destination:newWriter())

assert(writer:write("complete"))
assert(writer:close())
destination:close()
```

<a id="tecs.Scope"></a>
### tecs.Scope <span class="tealdoc-kind-badge tealdoc-kind-interface">interface</span>

`Scope` owns resources while preserving each concrete type.


```teal
interface tecs.Scope
    name: string

    own: function<T is Closeable>(self, value: T, reason: string): T
end
```

<a id="tecs.Scope.name"></a>
#### tecs.Scope.name <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Reports the diagnostic name supplied to `scoped`.


```teal
tecs.Scope.name: string
```

<a id="tecs.Scope.own"></a>
#### tecs.Scope:own <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Registers one owned value for cleanup and returns it unchanged.

The scope is active only inside the callback passed to `scoped`.
Calling a captured scope after that callback returns, raises, or begins
cleanup raises instead of creating an ownership obligation nobody will
run.
Passing nil raises with `reason` when one is supplied, which lets a
constructor's `value, reason` result pass directly to `own`. Without a
supplied reason, or with a value that has no `close` method, `own`
raises its own argument error.



```teal
function tecs.Scope.own<T is Closeable>(
    self, value: T, reason: string
): T
```

##### Type Parameters

| Name | Constraint | Description |
| --- | --- | --- |
| `T` | [`Closeable`](/modules/#tecs.Closeable) |  |

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Scope` | The active scope that will own the value. |
| `value` | `T` | An open [`Closeable`](/modules/#tecs.Closeable) or Lua file. Each call adds one cleanup obligation, including repeated calls with the same value. |
| `reason` | `string` | The operational failure returned beside a nil value. `own` raises this string at the call site. |

##### Returns

| Type | Description |
| --- | --- |
| `T` | The same value with its concrete type unchanged. |

## Functions

<a id="tecs.batch"></a>
### tecs.batch <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span>

Runs callbacks at the same time and returns their results in order.

Inside a system the call suspends until every callback settles, and
outside one it blocks while driving the producers they wait on. The
first callback that raises, in the order the callbacks were given,
cancels the rest, waits for them to unwind, and raises that failure.
Each callback reports once. Callbacks return values for the caller to
apply; staging world mutations inside them makes entity identifiers
depend on completion order.



```teal
function tecs.batch(bodies: {function(): any}): {any}
```

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `bodies` | `{function(): any}` | The caller supplies an array of functions that take no arguments. An empty array returns an empty array without waiting. |

#### Returns

| Type | Description |
| --- | --- |
| `{any}` | Returns one result per callback, at the callback's index, and that result is the callback's first return value. A batch mixes types freely, so the caller casts each result to what its own callback returned. |

<a id="tecs.scoped"></a>
### tecs.scoped <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span>

Runs a callback inside a fresh named resource scope and JIT zone.

The callback may suspend through a cooperative engine call inside a
system. Every value it registers closes in reverse order before this
function returns or propagates a failure. World shutdown also cancels
and unwinds a suspended system. Cleanup begins by making the scope
inactive, and one failing close does not prevent the remaining closes.



```teal
function tecs.scoped(name: string, body: function(Scope))
```

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `name` | `string` | The non-empty diagnostic and profiler-zone name. |
| `body` | `function(`[`Scope`](/modules/#tecs.Scope)`)` | The callback that receives the only active [`Scope`](/modules/#tecs.Scope) for this invocation. Returned values are ignored, and registered resources must not be used after the callback ends. |

#### Returns

None.

## Values

<a id="tecs.version"></a>
### tecs.version <span class="tealdoc-kind-badge tealdoc-kind-variable">variable</span>

Read-only. Version of this build.


```teal
tecs.version: string
```