Using xlibs and AlifePlus

What They Are

xlibs is an engine abstraction layer for STALKER Anomaly. It wraps X-Ray engine APIs in safe Lua functions: squad operations, smart terrain queries, entity resolution, an event bus, MCM config, PDA messaging, logging, and profiling.

AlifePlus is a reactive behavior framework built on xlibs. Engine callbacks produce causes (a squad entered a smart terrain, an NPC died, a stash was looted). The pipeline routes causes to registered consequences (a nearby faction investigates, a revenge squad is dispatched). Throttling, protection, rate limiting, ownership, and lifecycle are handled by the framework. Mods register a predicate and a handler.

Both are published under the PolyForm Perimeter License. Addons, integrations, and modpacks are encouraged with visible credit.

License

Required: Visible credit -- "xlibs by Damian Sirbu" and/or "AlifePlus by Damian Sirbu".

xlibs: The Modder's Toolbox

xlibs wraps X-Ray engine APIs based on reading the engine source (X-Ray Monolith C++), the Anomaly scripting layer, modded executable extensions, and established patterns from reputable community mods. The API surface was validated through tracing and load testing the Anomaly engine using Grafana k6 and a custom benchmarking framework. Key modules:

Full docs: github.com/damiansirbu-stalker/xlibs

AlifePlus: Three Levels of Integration

Level 1: Listen to events (easiest, no AP internals)

Subscribe to AlifePlus cause events via xbus. This is the recommended starting point.

function on_game_start()
    xbus.subscribe("cause:massacre", function(data)
        -- data.position, data.level_id, data.total_deaths
        my_response(data)
    end, "my_mod_massacre")
end

Available events: cause:elite, cause:elitekill, cause:massacre, cause:squadkill, cause:basekill, cause:area, cause:wounded, cause:stash, cause:harvest, cause:needs.

Level 2: Register causes and consequences (intermediate)

Register your behavior with AP's pipeline. You get throttling, protection, rate limiting, and PDA for free.

-- Cause: detect something interesting
local function _predicate(trace, squad)
    if not is_interesting(squad) then return nil end
    return { cause = "cause:my_event", squad_id = squad.id, ... }
end

-- Consequence: react to it
local function _handler(event_data)
    if not xmath.chance(30) then return { code = ap_const.RESULT.CHANCE_NEXT } end
    local squad = xobject.se(event_data.squad_id)
    local base = xsmart.find_smart(squad.position, { filter = xsmart.is_base })
    xsquad.control_squad(squad, base, true)
    return { code = ap_const.RESULT.OK_STOP }
end

function on_game_start()
    for i = 1, #ap_const.RADIANT_CALLBACKS do
        ap_producer_reactive.register("cause:my_event",
            { callback = ap_const.RADIANT_CALLBACKS[i] }, _predicate)
    end
    ap_consumer.register("consequence:my_reaction",
        { event = "cause:my_event", priority = 20 }, _handler)
end

Level 3: Deep integration (coordinate first)

If you need access to AP's tracker, chase system, territory conquest, or other internal systems -- reach out via the GitHub page. These APIs are not yet stable or documented for external use. The plan is to stabilize them as proper public APIs based on what mod authors actually need.

Architecture

Problem

Most alife mods for Anomaly hook engine callbacks independently, iterate over squads on a timer, implement their own throttling, check squad validity in their own way, and set engine fields directly. Each mod operates as a silo with no awareness of other mods controlling the same squads.

Design

xlibs and AlifePlus are designed as a shared alife layer that mods register to rather than build around.

• xlibs provides invariants: event bus (publish/subscribe), squad safety (protection checks, scripting, release), smart terrain queries, entity resolution, and a squad ownership protocol (claim/release with TTL, one owner at a time, framework-enforced lifecycle)
• AlifePlus provides the pipeline: a radiant callback dispatcher with rate limiting, a unified protection stack, cause/consequence routing via the event bus, and lifecycle management (scripting, arrival, cooldown, cleanup)
• Mods register domain logic: a predicate and a handler. The framework handles the rest.

What the framework provides

Mods that register with the pipeline get these facilities without implementing them:

Pipeline

Every squad event passes through the same sequence of gates. Each gate either passes the event forward or rejects it.

Integration examples

Planned

• Cause/consequence templates: reusable patterns (respond, chase, flee, patrol, guard) that mods instantiate with their own parameters instead of reimplementing squad scripting.
• xbus expansion: typed events with schemas, priority subscribers, event namespaces.
• Plugin SDK: documentation and a minimal example mod (~50 lines) showing how to register one cause and one consequence.