# `QuakeServer.EntityTable`
[🔗](https://github.com/jaman/quake_server/blob/v0.1.0/lib/quake_server/entity_table.ex#L1)

The entity references in a file the program carries from one level to the next,
translated by Half-Life's level transition rule (GoldSrc's engine and the HLSDK's
`CSaveRestoreBuffer`: a saved reference is an index into the save's entity table,
restored as the entity that table entry was restored into, and as null when the entry
was not carried into the level). The rule is Half-Life's (GoldSrc and the HLSDK), not
FreeHL's under FTE, where a number read back is the entity of that number in the new
level whatever it now is.

A file the program writes is read as entity text: blocks of lines between a `{` line
and a `}` line. A block's entry in the file's entity table is the first entity other
than the world the program runs as (`self`) while writing a line of the block, or none.
The table is kept with the written file when the program closes it
(`ext.entity_tables`, by the file's name under `data/`), moves with `frename`, is
dropped with the file (`fremove`), and goes to the next level with the program's
written files (`carry/1`, the server option `:entity_tables`).

While the program reads a carried file, from `fopen` until `fgets` reaches its end,
`fclose` closes it or `fremove` removes it, the entity the program runs as during a
block's lines, other than the world and the entity reading the file, is the entity the
block was restored into, and `edict_num` translates the number it is given
(`entity/2`):

  * the world and the player slots are kept: a player keeps its slot from level to
    level
  * an entity with a block becomes the entity the block was restored into; the world
    when the block was read without being restored into an entity or that entity has
    been freed
  * an entity with a block not yet read becomes an entity set aside for the block;
    when the reading ends every entity field holding it is set to the entity the block
    was restored into, or the world, and the set-aside entity is freed
  * any other number becomes the world: an entity of the level left that was not
    carried restores as null

A program reading a carried file, in QuakeC:

    fh = fopen("trans.dat", FILE_READ);
    while ((line = fgets(fh))) { ... e.owner = edict_num(stof(value)); ... }

# `t`

```elixir
@type t() :: %{entities: [non_neg_integer() | nil], carried: boolean()}
```

A written file's entity table: each block's entity, in order, and whether it came from an earlier level.

# `carry`

```elixir
@spec carry(%{required(String.t()) => t()}) :: %{required(String.t()) => t()}
```

The entity tables `tables` (a level's `ext.entity_tables`) as the next level takes them.

# `entity`

```elixir
@spec entity(map(), integer()) :: {map(), integer()}
```

The entity `number` stands for: translated through the entity table while the program
reads a carried file, `number` itself otherwise.

# `finish`

```elixir
@spec finish(map(), pos_integer()) :: map()
```

End the translation begun for file `handle`, settling the entities set aside.

# `forget`

```elixir
@spec forget(map(), String.t()) :: map()
```

Drop the entity table of written file `name`, ending a reading of it.

# `keep`

```elixir
@spec keep(map(), map()) :: map()
```

Keep the entity table of write file `file`, closed by the program, under its name.

# `observe`

```elixir
@spec observe(map()) :: map()
```

Note the entity the program runs as, while it reads a block of a carried file.

# `open`

```elixir
@spec open(map(), pos_integer(), String.t()) :: map()
```

Begin translating entity numbers if file `handle`, opened for reading from written
file `name`, has a carried entity table.

# `read`

```elixir
@spec read(map(), pos_integer(), String.t()) :: map()
```

Follow the line `line` the program read from file `handle`.

# `record`

```elixir
@spec record(map(), String.t(), non_neg_integer()) :: map()
```

Note on write file `file` (Store's file map, `mode: :write`) the blocks of `text`, written
as entity `writer`.

# `rename`

```elixir
@spec rename(map(), String.t(), String.t()) :: map()
```

Move the entity table of written file `from` to `to`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*