@v12-engine/engine 0.1.0 → 0.4.0

package/dist/foliage.d.ts

@@ -0,0 +1,476 @@
+import { type AreaShape } from './areas';
+import type { CellLayerDef } from './cellLayers';
+import { type ConcealmentOptions } from './concealment';
+import type { DamageType } from './defs';
+import { type Entity, type EntityId } from './entity';
+import { type Cancellable } from './hooks';
+import type { Vec2 } from './math';
+import type { GamePack } from './packs/pack';
+import type { World } from './world';
+/**
+ * The id of the foliage pack (`foliagePack`), for `hasPack`
+ *
+ * @beta
+ */
+export declare const FOLIAGE = "foliage";
+/**
+ * What has happened to a cell of grass or bushes, as the values of the layer's state layer (`foliageStateLayer`):
+ * `whole` (0: as it grew, and what a cell never touched is), `flattened` (crushed under what walked over it, or by
+ * `ruin`), `cut` (down to stubble: fire does not cross it), `burning`, `burnt` (charred: by a fire, or scorched by
+ * `ruin`), `growing` (coming back to whole). The style stays in the layer itself, so that what grows back is what
+ * stood there. Values past these are kept for states to come
+ *
+ * @beta
+ */
+export declare const FOLIAGE_STATE: {
+    readonly whole: 0;
+    readonly flattened: 1;
+    readonly cut: 2;
+    readonly burning: 3;
+    readonly burnt: 4;
+    readonly growing: 5;
+};
+/**
+ * What has happened to a cell of grass or bushes, by name (`FOLIAGE_STATE`)
+ *
+ * @beta
+ */
+export type FoliageState = keyof typeof FOLIAGE_STATE;
+/**
+ * The state a value of a state layer says (`FOLIAGE_STATE`): `whole` for a value that is none of them
+ *
+ * @beta
+ */
+export declare const foliageStateOf: (value: number) => FoliageState;
+/**
+ * The id of the layer of cells that keeps what happened to each cell of a layer of grass or bushes (`FOLIAGE_STATE`):
+ * `grass.state` for `grass`. A layer like any other (`Terrain.cells`, `world.setCells`): saved, told to the players who
+ * see a cell and to the others as it comes into their sight, kept with a map that starts with a field already burnt.
+ * No game lists it (`Rules.cellLayers`), so the editor does not offer it to paint
+ *
+ * @beta
+ */
+export declare const foliageStateLayer: (layer: string) => string;
+/**
+ * The layer a state layer is the state of (`foliageStateLayer`): none for a layer that is not one
+ *
+ * @beta
+ */
+export declare const foliageLayerOfState: (layer: string) => string | undefined;
+/**
+ * What a style of grass or bushes is to the rules: a value of a layer's cells (`CellLayerValue.foliage`), said in the
+ * game's code, in its `data.json` (`GameData.cellLayers`, every map) or in a map (`GameMap.definitions`, that map
+ * alone), each over the one before field by field. Plain data, every field: the editor writes it. What a value does
+ * not say is the layer's (`FoliageLayerOptions.style`), then what each field says it is when left out
+ *
+ * @beta
+ */
+export interface FoliageStyleDef {
+    /** Whether it hides who stands in it from the teams that have nobody in the same patch (`ConcealmentOptions`): no when left out */
+    conceals?: boolean;
+    /**
+     * Whether it hides what is taller than it stands (`height`): yes when left out. With `false`, a unit taller than the
+     * grass is seen over it (`FoliageConceal.heightOf`)
+     */
+    concealsTaller?: boolean;
+    /** How tall it stands to the rules, in cells: what `concealsTaller` is measured against, 1 when left out. How it is drawn is the look's own height */
+    height?: number;
+    /**
+     * How fast one on foot goes through it, as a multiplier of its speed (as `CellLayerDef.speed`, for this value alone):
+     * the layer's `speed` when left out, and 1 where the layer says none either
+     */
+    speed?: number;
+    /**
+     * Whether one on foot may walk through it: yes when left out. A hedge nothing goes through with `false`: the ways go
+     * round it as round a wall, whatever its state (a burnt hedge still stops, until its style is changed). Painted or
+     * cleared in play, the navigation's tiles it reaches are cut again: a few milliseconds a call on a big map, so not a
+     * call a tick
+     */
+    walkable?: boolean;
+    /** How easily it catches fire from a burning cell beside it, 0 (never: a firebreak) to 1 (as dry grass): 0 when left out, and nothing burns */
+    flammable?: number;
+    /** How many seconds a cell of it burns before it is burnt: 6 when left out */
+    burns?: number;
+    /** How hot it burns: how much likelier than 1 a burning cell of it is to light those beside it. 1 when left out */
+    fuel?: number;
+    /** Seconds after it was burnt, cut or flattened that it starts to grow back by itself; `false` for never (until `regrow`). Never when left out */
+    regrows?: number | false;
+    /** Seconds it takes to grow back once it starts by itself (`regrows`): hiding as it grows, whole at the end. 10 when left out */
+    grows?: number;
+    /**
+     * What walking over it does to it, to the rules: `crush` lays it flat for good (`flattened`, which hides nobody)
+     * under those the layer says (`FoliageLayerOptions.tramples`); `none` when left out. How it bends on the screen
+     * and stands up again is the look's (`FoliageLook.walked`)
+     */
+    trample?: 'none' | 'crush';
+}
+/**
+ * How a layer of grass hides who stands in it (`FoliageLayerOptions.conceal`): what `ConcealmentOptions` says of it,
+ * the layer aside, and how tall a unit stands
+ *
+ * @beta
+ */
+export interface FoliageConceal extends Pick<ConcealmentOptions, 'reach' | 'hides' | 'seenBy' | 'rustle' | 'rustleEvery'> {
+    /**
+     * How tall a unit stands, in cells, for the styles that do not hide what is taller than they are
+     * (`FoliageStyleDef.concealsTaller`): twice its type's `radius` when left out
+     */
+    heightOf?: (world: World, entity: Entity) => number;
+}
+/**
+ * One layer of grass or bushes of the pack (`foliagePack`): its id, what its styles are where they say nothing, how
+ * it hides and who tramples it
+ *
+ * @beta
+ */
+export interface FoliageLayerOptions {
+    /** The layer of cells (`Rules.cellLayers`): its values are the styles (`CellLayerValue.foliage`) */
+    layer: string;
+    /** What every style of the layer is where it says nothing of its own: a layer of one kind of grass says it all here */
+    style?: FoliageStyleDef;
+    /** How it hides who stands in the styles that conceal (`FoliageConceal`): `reach`, what it hides, the rustle */
+    conceal?: FoliageConceal;
+    /**
+     * Who crushes the styles that are crushed (`FoliageStyleDef.trample`), asked of a unit as it moves over one: every
+     * unit that walks when left out (not structures, nor what flies or sails), since a style is crushed only where it
+     * says so. A game's own for the heavy ones alone: `(world, unit) => unit.def.radius >= 1`
+     */
+    tramples?: (world: World, entity: Entity) => boolean;
+}
+/**
+ * How fire goes in a game's grass and bushes (`FoliageOptions.fire`): how often it spreads, what the wind and the
+ * slope do to it, how much may burn at once, what it does to who stands in it
+ *
+ * @beta
+ */
+export interface FoliageFire {
+    /** Whether a burning cell lights those beside it: yes when left out. With `false`, only what is set alight burns */
+    spread?: boolean;
+    /** How often a burning cell tries to light those beside it, in seconds: 0.25 when left out */
+    every?: number;
+    /** How much the wind decides which way it goes (`MapEnvironment.wind`), 0 (not at all) and up: 1 when left out */
+    wind?: number;
+    /** How much faster it goes uphill than down, 0 (the same) and up: 1 when left out */
+    slope?: number;
+    /** How strong a wind (0 to 1) has it jump a gap of one cell: never when left out */
+    jump?: number;
+    /** How wet everything is, 0 (dry) to 1 (nothing catches): 0 when left out */
+    wet?: number;
+    /** Whether rain and snow damp it and put it out (`MapEnvironment.weather`): yes when left out */
+    weather?: boolean;
+    /** The most cells that burn at once, over all the pack's layers: those past it wait their turn. 4000 when left out */
+    maxBurning?: number;
+    /** Seconds after which a fire dies, whatever is left to burn: never when left out */
+    lasts?: number;
+    /** Damage a second to units that stand in a burning cell, by whoever lit it: none when left out */
+    damage?: number;
+    /** The type that damage is dealt as: magic when left out */
+    damageType?: DamageType;
+    /**
+     * Whether a burning cell may set alight what burns and stands on it or on a cell next to it (trees, a wooden wall:
+     * grass does not burn under what stands), in a game with the burning pack too (`burningPack`): no when left out. It
+     * passes as fire does, not at once: at each of the cell's tries (`every`), by a chance of its own (0.05 for grass
+     * of `fuel` 1 in still, dry air, likelier downwind), asked of the game (`burnStart`, `cause: 'foliage'`), under the
+     * most that may burn there (`BurningOptions.maxBurning`). What caught is set alight at the end of the burning pack's
+     * turn, and tries nothing before its own next turn. The other way is that pack's to say (`BurningOptions.lightsFoliage`)
+     */
+    lights?: boolean;
+}
+/**
+ * What the foliage pack is made with (`foliagePack`): a layer of grass or bushes with its settings, more layers beside
+ * it, and how fire goes in them all
+ *
+ * @beta
+ */
+export interface FoliageOptions extends FoliageLayerOptions {
+    /** More layers of the same pack, each with settings of its own: fire passes from one to the next where both grow */
+    also?: FoliageLayerOptions[];
+    /** How fire goes (`FoliageFire`); `false` for a game whose grass never burns */
+    fire?: FoliageFire | false;
+}
+/**
+ * The layers a foliage pack was made with, each with its settings: the first, then those beside it (`FoliageOptions.also`)
+ *
+ * @beta
+ */
+export declare function foliageLayers(options: FoliageOptions): FoliageLayerOptions[];
+/**
+ * What a style of a layer is to the rules, by its value: what the value says (`CellLayerValue.foliage`, the game's
+ * code with its data and the map's over it) over the layer's own (`FoliageLayerOptions.style`). None for 0, which is
+ * no grass. A value the layer does not list is the layer's own style
+ *
+ * @beta
+ */
+export declare function foliageStyle(game: {
+    cellLayers?: readonly CellLayerDef[];
+    packs?: readonly GamePack[];
+}, layer: string, value: number): FoliageStyleDef | undefined;
+/**
+ * Why a style said as data is not one (`FoliageStyleDef`), where it is first wrong: nothing for one that is. `what`
+ * names it in what is said
+ *
+ * @beta
+ */
+export declare function foliageStyleProblem(said: unknown, what: string): string | undefined;
+/**
+ * Where something is done to grass: a shape on the ground, or cells by their indices (as `world.setCells` takes them)
+ *
+ * @beta
+ */
+export type FoliageWhere = AreaShape | readonly number[];
+/**
+ * A cell of grass or bushes as the rules know it now (`foliageAt`)
+ *
+ * @beta
+ */
+export interface FoliageCell {
+    /** The cell's index in the layer, row by row */
+    cell: number;
+    /** The style painted there: the layer's value, 1 to 255 */
+    value: number;
+    /** What that style is to the rules (`foliageStyle`) */
+    style: FoliageStyleDef;
+    /** What has happened to it (`FOLIAGE_STATE`) */
+    state: FoliageState;
+    /** Whether it burns now */
+    burning: boolean;
+    /** Seconds it still burns, 0 where it does not */
+    left: number;
+    /** Who set alight the fire it burns of, where someone did */
+    by?: EntityId;
+}
+/**
+ * How grass is ruined (`ruin`): `cut` to stubble (a firebreak), `crush` flat, `scorch` black with nothing left to burn
+ *
+ * @beta
+ */
+export type FoliageRuin = 'cut' | 'crush' | 'scorch';
+/**
+ * A cell of grass about to catch fire (the `foliageIgnite` hook): set alight (`ignite`, an ability) or lit by a cell
+ * burning beside it. `cancel()` keeps it from catching; `chance` is a handler's to change (a wet valley, a blessed
+ * grove)
+ *
+ * @beta
+ */
+export interface FoliageIgnite extends Cancellable {
+    /** The layer the cell is of */
+    readonly layer: string;
+    /** The cell's index in the layer */
+    readonly cell: number;
+    /** The cell's middle along the map's x axis */
+    readonly x: number;
+    /** The cell's middle along the map's z axis */
+    readonly z: number;
+    /**
+     * Whether it was set alight (`ignite`), caught from a neighbour (`spread`), or caught from a burning thing beside it
+     * (`burning`: a tree of the burning pack, `BurningOptions.lightsFoliage`)
+     */
+    readonly cause: FoliageCause;
+    /** The burning cell it catches from, for a spread */
+    readonly from?: number;
+    /** The burning thing it catches from, for one caught from a burning thing (`burning`) */
+    readonly thing?: Entity;
+    /** Who set alight the fire it is of, where someone did */
+    readonly by?: Entity;
+    /**
+     * How likely it is to catch, 0 to 1, as the style, the wind, the slope and the wet make it: 1 for one set alight.
+     * What a handler leaves it at is held to 0 to 1 (more than 1 is sure, less than 0 never)
+     */
+    chance: number;
+}
+/**
+ * How a cell of grass caught fire (`FoliageIgnite.cause`, `foliageIgnited`): set alight (`ignite`, an ability), caught
+ * from a burning cell beside it (`spread`), or from a burning thing beside it (`burning`: `BurningOptions.lightsFoliage`)
+ *
+ * @beta
+ */
+export type FoliageCause = 'ignite' | 'spread' | 'burning';
+/**
+ * Asked before a cell of grass catches fire (`FoliageIgnite`): a handler refuses it or changes its chance. For every
+ * cell a fire tries, so a handler does little
+ *
+ * @beta
+ */
+export declare const foliageIgnite: import("./hooks").HookKey<FoliageIgnite>;
+/**
+ * Cells of grass caught fire this tick, by layer and cause: what a game's rules and its computer players hear. The
+ * screens are told by the state layer's cells, each as far as it sees
+ *
+ * @beta
+ */
+export declare const foliageIgnited: import("./events").EventKey<{
+    layer: string;
+    cells: number[];
+    cause: FoliageCause;
+    by?: EntityId;
+}>;
+/**
+ * Cells of grass burnt out this tick: charred now, to grow back where their style says
+ *
+ * @beta
+ */
+export declare const foliageBurnt: import("./events").EventKey<{
+    layer: string;
+    cells: number[];
+}>;
+/**
+ * Cells of grass were ruined (`ruin`, `firebreak`, an ability, what tramples): how, and by whom where someone did
+ *
+ * @beta
+ */
+export declare const foliageRuined: import("./events").EventKey<{
+    layer: string;
+    cells: number[];
+    how: FoliageRuin;
+    by?: EntityId;
+}>;
+/**
+ * Cells of grass are whole again: grown back by themselves, or by `regrow` (by whom, where it said)
+ *
+ * @beta
+ */
+export declare const foliageRegrown: import("./events").EventKey<{
+    layer: string;
+    cells: number[];
+    by?: EntityId;
+}>;
+/**
+ * The last burning cell of a layer went out: burnt out, put out or stopped
+ *
+ * @beta
+ */
+export declare const foliageFireOut: import("./events").EventKey<{
+    layer: string;
+}>;
+/**
+ * Grass and bushes in the rules, on a layer of cells whose values are styles (`CellLayerValue.foliage`,
+ * `FoliageStyleDef`): the styles that conceal hide who stands in them (as `concealmentPack`, patch by patch, while
+ * they stand whole), a style may slow or stop one on foot, be crushed under who walks over it, be ruined and grow
+ * back, catch fire and pass it on (`FoliageFire`). What happened to each cell is kept in the layer's state layer
+ * (`foliageStateLayer`). One a game:
+ *
+ *     export const rules = { ...myGame, packs: [foliagePack({ layer: 'grass', fire: { damage: 8 } })] }
+ *
+ * A layer of the pack is not given to `concealmentPack` too: the pack hides in it by itself. Its styles are read from
+ * the game's layers as laid (`foliageStyle`: the code, the game's `data.json`, the map's definitions), so a style the
+ * editor made hides and slows as one of the code's. What it does today: hiding by style and state, a style's
+ * `speed` and `walkable`, trampling (`trample: 'crush'`, by who `tramples` says), fire (`ignite`, `FoliageFire`) with
+ * `firebreak`, `extinguish` and `stopFire`, ruin (`ruin`) and growing back (`regrow`, by itself where a style
+ * `regrows`), and the `foliage` ability effect
+ *
+ * @beta
+ */
+export declare function foliagePack(options: FoliageOptions): GamePack;
+/**
+ * Sets grass alight: the cells there that can burn start burning (`foliageIgnite` is asked of each), and the fire
+ * goes on from them. `by`: who lit it, whom its damage is dealt by. A cell catches where its style burns
+ * (`flammable` over 0), it stands whole or grows back, and it is not on water, a road (the game's `road` tile), what
+ * blocks the way or under a building. Past the most that may burn at once (`FoliageFire.maxBurning`), the rest wait
+ * their turn. Returns the cells that caught, in order; none in a game whose grass does not burn (`fire: false`)
+ *
+ * @beta
+ */
+export declare function ignite(world: World, layer: string, where: FoliageWhere, options?: {
+    by?: Entity;
+}): number[];
+/**
+ * Puts out what burns there: the cells stop burning as they are, burnt. Returns the cells put out, in order
+ *
+ * @beta
+ */
+export declare function extinguish(world: World, layer: string, where: FoliageWhere): number[];
+/**
+ * Cuts grass down to stubble, which fire does not cross: `ruin` with `cut`. What burns there stops burning, cut. A
+ * cell burnt already, or cut, is left as it is. Returns the cells cut, in order
+ *
+ * @beta
+ */
+export declare function firebreak(world: World, layer: string, where: FoliageWhere, options?: {
+    by?: Entity;
+}): number[];
+/**
+ * Puts out every fire of a layer, or of all the pack's layers when none is named: what burns is burnt, what waits its
+ * turn is not lit. Returns how many cells were burning
+ *
+ * @beta
+ */
+export declare function stopFire(world: World, layer?: string): number;
+/**
+ * Ruins grass: cut to stubble (`cut`, state `cut`: a firebreak), crushed flat (`crush`, state `flattened`, as what
+ * tramples it does) or scorched black (`scorch`, state `burnt`: nothing left to burn) (`FoliageRuin`). What burns there
+ * goes out as it is ruined. It hides nobody and does not burn until it has grown back (`regrow`, or by itself after
+ * its style's `regrows` seconds, over its `grows`). A cell is left as it is where it is that already, or burnt (nothing
+ * to cut or crush), or cut (nothing to crush). Told (`foliageRuined`), by `by` where it says. Changes the state layer
+ * alone: the ways are not weighed again. Returns the cells ruined, in order
+ *
+ * @beta
+ */
+export declare function ruin(world: World, layer: string, where: FoliageWhere, options: {
+    how: FoliageRuin;
+    by?: Entity;
+}): number[];
+/**
+ * Has ruined or burnt grass (cut, flattened, burnt) grow back to what it was: over `over` seconds (growing, which
+ * hides and burns as whole grass does, and whole at its end), or at once when left out or 0, when grass growing back
+ * already stands whole at once too. What it waited for by itself (`regrows`) it waits for no more. Told as it is whole
+ * (`foliageRegrown`), by `by` where it says. Returns the cells that started to, in order
+ *
+ * @beta
+ */
+export declare function regrow(world: World, layer: string, where: FoliageWhere, options?: {
+    over?: number;
+    by?: Entity;
+}): number[];
+/**
+ * Takes grass away for good: the cells are no style any more (0), and nothing grows back. Returns the cells cleared
+ *
+ * @beta
+ */
+export declare function clearFoliage(world: World, layer: string, where: FoliageWhere): number[];
+/**
+ * Paints grass of a style: `world.setCells` on the layer, checked (a value the layer has a style for, or 0), the
+ * cells whole again. Returns the cells that changed
+ *
+ * @beta
+ */
+export declare function setFoliage(world: World, layer: string, where: FoliageWhere, value: number): number[];
+/**
+ * The grass at a point as the rules know it (`FoliageCell`): its style, what happened to it, whether it burns. None
+ * where no grass is, or off the map
+ *
+ * @beta
+ */
+export declare function foliageAt(world: World, layer: string, x: number, z: number): FoliageCell | undefined;
+/**
+ * The cells of a layer that burn now, in order of their indices: for a game's rules and its computer players. Not to
+ * be kept or changed: the pack's own list. None in a game whose grass does not burn
+ *
+ * @beta
+ */
+export declare function burningCells(world: World, layer: string): readonly number[];
+/**
+ * A gust of wind at a place, for the grass and bushes there to bend to: an explosion's ring, a dragon's wings
+ *
+ * @beta
+ */
+export interface WindGust {
+    /** How far around it reaches, in cells */
+    radius: number;
+    /** How hard it blows, as the wind's strength: 1 a gale */
+    strength: number;
+    /** Which way it blows, in degrees as the wind's (`MapWind.around`): outwards from its middle when left out */
+    around?: number;
+    /** How many seconds it lasts: 0.6 when left out */
+    lasts?: number;
+}
+/**
+ * A gust of wind at a place, on the screen of every player who sees it (`WindGust`): the grass bends to it there (a
+ * ring outwards as it spreads, or a push one way where it says `around`), as `client.gust` bends it on one screen. A
+ * player is told where their team sees its middle or any of its edge; an observer always. Nothing it does decides
+ * anything: it is not in the world's state or a save, and it changes nothing of the world
+ *
+ * @beta
+ */
+export declare function gust(world: World, at: Vec2, gust: WindGust): void;
+/** A gust of wind (`gust`): to each player whose team sees its middle or its edge, as a `gust` message */
+export declare const toldGust: import("./replication").ReplicatedEvent;