Crate enshwick 

The Enshwick modding API for Enshrouded: what a mod is written against.

A mod is a DLL in the game’s mods/ folder. It implements Mod, exports itself with declare_mod!, and during Mod::init links hooks declared with detour! or #[hook] through Load::hook, reads its settings and finds game functions by name. The loader arms every hook once all mods are initialised; a mod that fails or panics is turned off and the game runs vanilla where it acted.

Depend on this crate from crates.io; cargo enshwick new writes the lines. The derive and attribute macros come from enshwick-macros, which this crate re-exports:

[dependencies]
enshwick = "<version>"

[dev-dependencies]
enshwick = { version = "<version>", features = ["test"] }

A mod builds for x86_64-pc-windows-msvc, the game’s target. The crate also builds on other hosts, so a mod’s tests run against the fake loader anywhere.

Modules

Area	Modules
The mod and the loader	Load, Host, abi, mods, config, i18n, status, state, migrations
Hooks and game memory	detour!, hook, code, ecs, raw, pacing
Events and timing	events, game_events, schedule, time
The server’s world	altars, buffs, daytime, effects, game_settings, terrain, voxels, weather
Players and their things	inventory, item_data, entity_data, interactions, knowledge, progress
Game rules	damage, loot, stats, affixes, survivors, vetoes
Content	content, packs
Between mods	services, points, net, shape
Interface	ui
Unstable, with the unstable feature	world, map, actions, console, rates, script
Tests	test, with the test feature

Items marked unstable may change in any release; everything else keeps the compatibility rules of the version. The book’s Stability chapter names what is unstable and why.

Features

• test — test: a fake loader for a mod’s unit tests.
• schema — packs::schemas: the JSON Schemas of a data pack’s files, for tools.
• unstable — unstable: the parts of the API that may still change in any release: young APIs and calls that rest on engine facts not yet checked in the running game. Every item it adds is marked in the docs.

Examples

/// Hello's settings.
#[derive(Default, serde::Deserialize, serde::Serialize, enshwick::Config)]
struct Settings {
    /// Whether the hook goes in.
    enabled: bool,
}

struct Hello {
    settings: Settings,
}

enshwick::detour! {
    static UPGRADE: unsafe extern "system" fn(ctx: *mut u64) = upgrade;
}

fn upgrade(next: enshwick::Next<unsafe extern "system" fn(*mut u64)>, ctx: *mut u64) {
    // SAFETY: the original takes the same context.
    unsafe { next.get()(ctx) }
}

impl enshwick::Mod for Hello {
    fn manifest() -> &'static enshwick::abi::Manifest {
        enshwick::manifest!(id: "you.hello", side: SERVER)
    }

    fn init(load: &mut enshwick::Load<'_>) -> Result<Self, enshwick::Off> {
        let settings: Settings = load.config()?;
        if settings.enabled {
            let target = load.system("upgrade_building_range")?;
            // SAFETY: the system takes the building context, as `UPGRADE` does.
            unsafe { load.hook(&UPGRADE, target) }?;
        }
        Ok(Self { settings })
    }
}

enshwick::declare_mod!(Hello);

Re-exports

pub use abi::Entity;

pub use abi::ItemId;

pub use abi::PlayerKey;

pub use abi::RecipeId;

pub use shape::Shape;

Modules

abi

The binary interface between the loader and a mod DLL.

actionsunstable

Player actions: what a player asks a mod to do, declared once and offered in the game’s interface.

affixes

Affixes: named bundles of stat modifiers with rolled values, such as “of the Bear” giving 10 to 30 extra health, rolled onto single items as they drop or are crafted and kept with the item.

altars

Flame Altars of the server’s world: where they stand, their levels, their building zones and the bases those zones form; the sizes a mod gives the zones; and building across the seams between zones.

buffs

Buffs and debuffs in the server’s world: the types the game knows, the buffs an entity has, giving one and removing one.

code

Byte patterns that find game code without fixed addresses.

config

Typed mod settings, in mod-configs/<id>.toml beside the game.

consoleunstable

The server’s console: lines a tool runs on the server as an administrator with no character, such as each line of a dedicated server’s command file.

content

Game content from mods: new resources such as items and recipes, and changes to vanilla ones, served to the game as if they came from its archive.

damage

Damage filters: see and change damage before it reaches an entity’s health in the server’s world, by cause and, for hits, by damage type.

daytime

The clock of the server’s world: the time of day, setting it, how fast it runs, and the turns of day and night.

ecs

Access to the engine’s ECS from inside a hooked system.

effects

Effects in the server’s world: game events a mod raises, teleports and spawns.

entity_data

Data a mod attaches to any entity, such as a placed chest’s owner or a survivor’s nickname: typed values in kinds named <mod>:<name>, kept per world and, for kinds that ask for it, sent to players.

events

Typed loader events, and the Kind that Load::on takes for them and for the typed game events.

game_events

Game events: the ECS events the server’s systems raise, such as a hit, a death or a level gained, observed typed through Load::on or by reflected type.

game_settings

The server’s game settings: the difficulty and gameplay values of its configuration (gameSettings in enshrouded_server.json) or of the host’s world menu, read typed and changed while the world runs.

i18n

Translations: a mod ships its texts per language in one TOML file, a server owner may add to them or change them, and the game shows them for the player’s language.

interactions

Players’ interactions with entities.

inventory

Inventories on the server: read what a chest, corpse or player holds, and change it through the game’s own transactions.

item_data

Data a mod attaches to single items, such as a staff’s owner or a ring’s rolled bonus: typed values in kinds named <mod>:<name>, kept per world and sent to players.

knowledge

Knowledge in the server’s world.

loot

Loot containers on the server: the corpses and loot bags a dead enemy leaves, and other containers that dissolve once emptied.

mapunstable

The world’s map as the server knows it: its markers, its frame and each player’s waypoint.

migrations

Migrations: what a new version of a mod changes in what older versions left behind, run once per world and recorded.

mods

The mods the loader loaded, for mods that look after other mods.

net

Messages between a mod’s server part and its client part.

pacing

How the engine paces its loops and sizes its thread pools: the places a mod changes to make the game use less CPU.

packs

Data packs: items, recipes, workshops, loot and texts described in TOML files instead of code, and changes of vanilla values.

points

Extension points: rules one mod lets other mods observe, advise or override.

progress

Character progress: skill node checks, the comfort furniture gives a base, and the experience the server applies each tick.

ratesunstable

Game rates: multipliers on what the game hands out, such as experience.

raw

Reads and writes of game memory at byte offsets, for structs the API does not wrap: a field at an offset from Load::field_offset or Load::constant, inside a context or component a hook was given.

schedule

Work for the server’s game thread: on the scheduler’s next pass, after a delay, or repeatedly.

scriptunstable

What the API offers a script language, described beside the Rust items.

services

Typed services and events between mods.

shape

The shape of a type that crosses between mods: what the layout checks of services, mod events and extension points hash for every field.

state

State that outlives a session, in the mod’s data folder.

stats

Stats: named numbers on entities, such as extra health or a chance to crit, that items, buffs and mods modify, worked out once per change and read for free.

status

Status lines: what a mod reports about itself in the loader’s status summary, logs/enshwick/status.log, written every few minutes and on enshwick status on the server console.

survivors

Survivors: who answers the game’s question “which entity is this survivor”, their beds, summoning staffs and the client’s survivor menu.

terrain

Terrain in the server’s world: the terrain materials, and adding, digging and flattening ground as the game’s terraforming does.

testtest

A fake Enshwick loader for a mod’s unit tests.

time

Time that runs with the server’s simulation steps, for waits that should not run out while the server stands still.

ui

The client’s interface, drawn with the game’s own widgets.

vetoes

Vetoes: a mod’s say before the game crafts or builds. Interactions with entities, from opening a chest to dismantling a piece, have their own filter in interactions.

voxels

Voxels of the server’s world: what the ground and the building blocks are made of, voxel by voxel.

weather

Weather in the server’s world: how it is at a place, the fronts that make it, and starting new weather.

worldunstable

The server’s world: components, entities and players, their queries and writes, chat, saves, build rights and Transactions.

Macros

debug

Logs a line at debug level under the mod’s id; formats like format!.

declare_mod

Exports a Mod from the DLL: the five functions of abi::exports, each catching panics.

detour

Declares a hook: a static Hook and the entry point the loader links into the chain.

error

Logs a line at error level under the mod’s id; formats like format!.

error_every

Logs a line at error level at most once per period from this call site, noting how many it skipped since the last.

error_once

Logs a line at error level the first time this call site runs only.

info

Logs a line at info level under the mod’s id; formats like format!.

info_every

Logs a line at info level at most once per period from this call site, noting how many it skipped since the last.

info_once

Logs a line at info level the first time this call site runs only.

manifest

Builds a mod’s static Manifest.

warn

Logs a line at warn level under the mod’s id; formats like format!.

warn_every

Logs a line at warn level at most once per period from this call site, noting how many it skipped since the last.

warn_once

Logs a line at warn level the first time this call site runs only.

Structs

Hook

A mod’s link for one game function: its detour and the slot through which it reaches the rest of the chain.

Host

The loader’s services for this mod, valid for the life of the process.

Load

The loader during a mod’s initialisation: lookups, hooks, settings and services.

Next

What a detour calls to continue: the next link, or the game’s original function.

Off

Why a mod turns itself off during initialisation; the loader logs the reason and keeps the game vanilla where the mod would have acted.

Enums

WorldError

Why the server’s world refused a request.

Constants

VERSION

The version of this crate, which a mod’s generated Cargo.toml pins.

Traits

FnPtr

A function pointer with the system ABI that a hook can stand in for.

Mod

A mod: what the loader initialises when it loads the DLL.

Functions

host

The loader’s services, once the loader has initialised this mod.

Attribute Macros

callunstable

Declares a call, a described service: one function from the input struct to an answer, which this mod serves and others call. The struct becomes repr(C) and implements services::Call with a layout hash per field and one for the answer, which the loader checks for every caller.

event

Declares a mod event other mods subscribe to: the struct becomes repr(C) and implements services::ModEvent with a layout hash per field.

hook

Declares a hook from its body, as detour! does: the function stays, and a static Hook named after it in upper case joins it.

point

Declares an extension point other mods extend: the input struct becomes repr(C) and implements points::Point with a layout hash per field and one for the answer, which the loader checks for every link.

scriptunstable

Exports the methods of an impl block marked #[script] to script languages: #[script(<part>)] adds the constant SCRIPT_<PART>, a list of script::Function a script::Bound type names in its parts.

service

Declares a service table other mods use: the struct becomes repr(C) and implements services::Service with a layout hash per field, which the loader checks when a mod asks for the service.

Derive Macros

Config

Implements enshwick::config::Config for a struct with named fields.

Scriptunstable

Describes a type for script languages through script::Typed, script::IntoScript and, when every field is shown, script::FromScript.

Shape

Derives Shape for a type that crosses between mods inside a #[service], #[event] or #[point], so a change inside it refuses the link.