API Reference Cauldron2D v#0.2.2

A 2D tile engine for terminals: a grid of tile ids, drawn as pixels or as glyphs depending on what the terminal supports.

A named catalogue of tiles.

The atlas.txt beside an art directory's pictures: what a text renderer draws for each art, and how fast its frames go.

Owns every atlas's composited-tile cache table, so a table outlives whichever process installed the atlas.

Sound effects and music for one listener, over one TuningFork stage.

A sound event under a key, as Cauldron2D.Audio.keyed/4, moved/2 and stopped/2 build it for Cauldron2D.Audio.play/2.

Music in sections and layers, switched on bar boundaries and mixed per listener.

Every sound a game plays, rendered once: a TuningFork.Voice at a rate becomes mono PCM the first time it is asked for and is kept in an ETS table for every stage on the node after, whatever its gain or pan, which are applied to the copy each time.

How a server on the local network is found: the host says so every two seconds on a UDP port — port/0, the :beacon_port in the :cauldron_2d config, 2299 unless set — to the broadcast address and to this machine, and whoever listens (Cauldron2D.Beacon.Listener) hears it.

Hears the servers of one game calling on the local network (Cauldron2D.Beacon) and keeps those heard in the last six seconds.

Source-over compositing of two equal-sized RGBA rectangles.

A point mass with a heading: position, velocity, and one of headings directions.

Resolves which part of a world is on screen.

A camera that trails its target and can be shaken, as a value the game steps.

What a game gives a client — the terminal's, the browser's or the desktop's — to put its worlds in front of a player. One contract; every front end draws from it.

The shapes a game's hud comes in, and one form every front end reads.

Bodies against a tile grid, and against each other.

Bodies sorted into square buckets, so that only neighbours are compared.

Play across machines over BEAM distribution: one machine hosts, the other joins its worlds (Cauldron2D.Worlds.world_name/2).

A frame as a list of pictures placed in pixels, and the raster it draws.

Fitting a frame of a fixed shape into a picture of another, with bars on the sides or above and below.

What a game gives Cauldron2D.World to run: a pure value and the callbacks that change it.

Ways across a tile grid of any size, for bodies that move through the open tiles.

The regions of a grid for Cauldron2D.Grid.Coarse: within each block of block tiles a side, the open tiles joined edge to edge, numbered from 1.

A* over a graph given as functions, as Cauldron2D.Grid.Coarse searches its regions and its tiles.

Positions on a grid of width by height tiles whose opposite edges join when wrap?, as Cauldron2D.Grid.Coarse measures them. Any map with those three keys is a space.

Recursive shadowcasting: which tiles an observer can see from where it stands.

Ways across a tile grid: breadth-first for the fewest steps, A* for the cheapest.

Turns terminal events into the set of actions a player is holding.

Turns game-controller events into the set of actions a player is holding.

Every player's results, kept on disk, and the boards made from them.

The lock that keeps a ledger file to one operating system process: <path>.lock, holding the process id of the holder. A lock whose process is gone counts as free; a file a DETS table of this process already has open is held.

One world's scribe: subscribed to its world's events (Cauldron2D.World.Events), it puts every {tag, row} — :result unless told otherwise — in the ledger under the world's name. It stops when the world does.

A fixed timestep.

A tile map written as text: a grid of characters, one per tile, with optional name: value options ahead of it.

Which pixels of a picture are solid, one bit each.

The whole map in a few rows of braille: walls in one colour, marks — players, bases, goals — over them, each a dot or a two-by-two.

Where cauldron_2d's compiled native code is: priv/native/<system architecture>, the architecture as :erlang.system_info(:system_architecture) gives it. Builds for different machines (macOS, Linux) sit side by side in one checkout, and each loads its own. The Makefile writes to the same folder, which mix.exs passes it as PRIV_DIR.

Whether placed shapes (Cauldron2D.Shape) touch each other, a point, a rectangle, a circle or a line.

A background of several depths, each read at its own share of the camera's motion.

Horizontal bands of one layer, each scrolling at its own factor.

One depth of a parallax background.

A layer that is one picture, repeated.

A camera moved across a set of layers, as a list of pictures.

A cell function that places art by hashing the tile's own coordinate.

A cell function over authored tiles, wrapping in one or both directions.

Short-lived sprites — sparks, debris, smoke — with a cap on how many exist at once.

Where a game keeps its files: one directory per game under each of the XDG base directories.

A player's side of a Cauldron2D.World: join, send input, receive frames, leave.

A framebuffer of RGBA rows that stamps are painted onto, and the stamps themselves.

Renders the world from a point inside it, looking along a heading: standing arts as textured walls of their height, floors textured to the horizon, movers and the standing arts of no height as billboards, everything fading towards the atlas's void colour with distance.

A projection drawn as one of the atlas's two-character glyphs per slot.

Samples a textured ground plane in perspective: for each pixel below the horizon the world point it looks at, the tile there, and that tile's texel, faded towards a void colour with distance.

Composes a view of the world as an isometric picture: floors as diamonds, standing arts as blocks with a top and two shaded sides, movers and flat overlays as upright sprites, painted back to front.

Composes the world as a ground plane seen in perspective from above it, turning freely: the floor recedes to a horizon, movers stand on it as billboards, and everything fades towards the atlas's void colour with distance.

Composes a view of the world on a square grid seen from above and in front: floors as squares, standing arts as a front face with their top above it, movers upright.

A coloured region of space that tints whatever is seen through it, and the arithmetic a projection draws one with.

The per-pixel half of Cauldron2D.Projection.Volume, in C.

What a projection needs to know about the shape of a Cauldron2D.Projection.Volume.

The shapes Cauldron2D.Projection.Volume knows without being told: a sphere, a cylinder, a cone, a beam, and a set of whole grid tiles.

A frame drawn once from a list of operations.

Chooses between drawing a surface as pixels or as glyphs.

A record of everything that was done to a world, and the means to do it again.

Plays a Cauldron2D.Replay back on a clock, sending a watcher the frames one recorded player saw.

A random number generator carried in a game's state rather than the process dictionary.

A computer player: a process that joins a world as {:robot, n} and plays by its view, deciding every few frames through a brain module the game supplies.

A way from where something stands to where it was sent, and walking it a step at a time.

Saved games: a game state kept on disk under a slot name, and read back to start a Cauldron2D.World from with its :state option.

A map of the level drawn from above, out of the lines the player has seen: as lines for Cauldron2D.Sectors.Frame.lines/2.

A sector map's lines, and the bodies moving through it, sorted into square blocks so that movement and traces only look at what is near.

A binary space partition of a sector map: the order to draw it in from any point, front to back, and the convex piece any point is in.

An indexed-colour picture drawn a column, a plane or a line at a time — the drawing a sector view does — and turned into RGBA through a palette at the end.

Light as table lookups: a ramp of light tables built from a palette, and which table a surface at some light level and distance is drawn through.

A level made of sectors: rooms of any shape, each with its own floor and ceiling height, joined and walled by lines, the geometry a sector view and sector movement read.

Moving a body through a sector map: whether it fits where it is going, what floor and ceiling it finds there, and sliding along a wall it runs into.

How far a sound carries through a sector map: from the sector it is made in, into every sector joined to it by an opening that is not shut.

A picture drawn flat on the frame, stretched to a rectangle: a held weapon, a status bar, a face, a menu.

The pictures a sector view draws from — wall textures, floor textures, sprites — and the light tables that darken them, held ready for Cauldron2D.Sectors.Frame.

Whether one point in a sector map can see a body: the straight line between them must pass through every opening it crosses, between floor and ceiling.

What a straight line across a sector map crosses, nearest first: the map's lines and the bodies filed in a Cauldron2D.Sectors.Blockmap.

Draws a sector map from a point inside it: walls, floors, ceilings and sky, and the things standing in it, nearest in front, into a Cauldron2D.Sectors.Frame.

Who is logged in on the node, by whatever kind of client, told to whoever asks.

A solid shape placed in world pixels, for collision.

A Cauldron2D.Atlas packed onto one raster, with an index of where every art is.

State tables: an actor's animation and behaviour as data, each state a picture shown for a number of ticks, an action run on entering it, and the state that follows.

How this node is keeping up: every running world as Cauldron2D.World.stats/1 gives it, and the node it runs on.

Choosing which of eight directions to walk toward a target, trying the next best when the best is blocked — the chase that makes a pursuer feel its way round corners without finding a path.

Composites a grid of cells into one FrenchCurve.Raster.

Drives a Cauldron2D.Game in a test, with no world process and no clock: join players, hold actions, run ticks, read views and events.

The things in a world that change by themselves each tick — a door closing, a lift waiting, a light flickering, a creature — kept in a fixed order so a world run twice from the same start runs the same.

A trace of what happened and when, written as one line per event, and read back for mix cauldron.report.

Every number that decides how a game plays, in one value the game carries in its state and a settings page can show and change.

The cosine and sine of an angle in degrees, exact for whole quarter turns so a picture or shape turned by 90, 180 or 270 degrees lands on the same pixels as one mirrored by hand.

Runs a Cauldron2D.Game at a fixed tick and keeps its players supplied with views.

A world's events, told each tick to processes that are not its players — a recorder, a referee, a bot that reads the game without playing it.

Who comes and goes in every world on the node, told to whoever asks.

The worlds a game offers: a Cauldron2D.World each, with whatever runs beside it, started on the first use of its name and stopped again once no player has been in it for a while.

The name registry behind Cauldron2D.Worlds.world_name/1: {:via, Cauldron2D.Worlds.OnDemand, id} resolves to world id, starting the world when it is not running. An id no world is registered for resolves to :undefined. {:on, node, id} (Cauldron2D.Worlds.world_name/2) resolves to world id of a connected node the same way, started there; :undefined when the node cannot be reached.

Stops worlds that have had no human in them for a while; they start again on the next use of their world's name. Each sweep also seats the children a running world is short of (Cauldron2D.Worlds.reseat/1).

The registered worlds, one record each, in an ETS table this process owns.

Summarise a trace written by Cauldron2D.Trace.