# tecs


## Module contents

### Submodules

| Submodule | Description |
| --- | --- |
| [`tecs.Application`](/modules/Application/) | The application lifecycle, entry plugin, frame, checkpoints, and crash state |
| [`tecs.Future`](/modules/Future/) | Settle-once values, asynchronous composition, waiting, cancellation, and sequence tracking |
| [`tecs.assets`](/modules/assets/) | Asynchronous byte, image, sound, and static glTF loading through futures |
| [`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.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/) | Binary I/O, nonblocking 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.runtime`](/modules/runtime/) | Process-wide polling for asynchronous work in applications and headless programs |
| [`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 connected by serialized task and result channels |

### 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 |
| --- | --- | --- |
| [`scoped`](/modules/#tecs.scoped) | <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span> | Runs a callback inside a fresh resource scope. |

### 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
    own: function<T is Closeable>(self, value: T, reason: string): T
end
```

<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.scoped"></a>
### tecs.scoped <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span>

Runs a callback inside a fresh resource scope.

The callback runs synchronously and must not yield. Every value it
registers closes in reverse order before this function returns or
propagates a failure. Cleanup begins by making the scope inactive, and
one failing close does not prevent the remaining closes.



```teal
function tecs.scoped(body: function(Scope))
```

#### Arguments

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