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 framework built on xlibs. Engine callbacks produce causes (a squad entered a smart terrain, an NPC died, a stash was looted). Two pipelines handle the flow: an Event Pipeline that filters engine noise into meaningful cause events, and a Dispatch Pipeline that routes causes to registered consequences (a nearby faction investigates, a revenge squad is dispatched). Protection, rate limiting, ownership, and lifecycle are handled by the framework. Mods register a predicate and a handler. The codebase is split into core (ap_core_* - pipeline, lifecycle, protection) and ext (ap_ext_* - domain logic). Core never imports ext.

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 Integration

Register: Add a Cause + Consequence

The primary way to extend AP. Register a predicate and a handler. The framework handles gates, protection, rate limiting, tracing, PDA routing, squad lifecycle.

-- ap_ext_cause_ambush.script
local CAUSE = ap_core_const.CAUSE
local CAUSE_TYPE = ap_core_const.CAUSE_TYPE
local RESULT = ap_core_const.RESULT
local REASON = ap_core_const.REASON
local cfg = ap_core_mcm.cfg

local function _predicate(trace, squad)
    if not cfg.cause_ambush_enabled then return { code = RESULT.FAILED_RULES } end

    local level_id = xlevel.get_level_id(squad)
    if not level_id then return { code = RESULT.FAILED_RULES, reason = REASON.NO_LEVEL_ID } end

    local smart = ap_core_utils.find_smart(squad.position, {
        level_id = level_id, max_distance = ap_core_const.RANGE_EYE,
        filter = xsmart.is_smart_empty,
    })
    if not smart then return { code = RESULT.FAILED_RULES, reason = REASON.NO_SMART } end

    return {
        cause = CAUSE.AMBUSH,
        squad_id = squad.id,
        community = squad.player_id,
        smart_id = smart.id,
        level_id = level_id,
        position = squad.position,
    }
end

function on_game_start()
    local cbs = ap_core_const.RADIANT_CALLBACKS
    for i = 1, #cbs do
        ap_core_producer.register(CAUSE.AMBUSH,
            { callback = cbs[i], cause_type = CAUSE_TYPE.RADIANT },
            _predicate)
    end
end

-- ap_ext_consequence_ambush_setup.script
local RESULT = ap_core_const.RESULT
local REASON = ap_core_const.REASON
local CONSEQUENCE = ap_core_const.CONSEQUENCE
local CAUSE = ap_core_const.CAUSE
local PHASE = ap_core_const.CONSEQUENCE_PHASE
local PERSONALITY = ap_ext_const.PERSONALITY
local cfg = ap_core_mcm.cfg

local _alignment = ap_ext_const.alignment_outlaw
local _personality = { PERSONALITY.AGGRESSION, PERSONALITY.GREED }

local function _on_arrive(squad, args)
    -- runs when squad reaches destination smart
end

local function _handler(event_data)
    local trace = event_data._trace
    return ap_core_debug.observe(trace, CONSEQUENCE.AMBUSH_SETUP, function()

        -- RULES: alignment, personality, validation
        if not ap_ext_util.check_alignment(_alignment, event_data.community) then
            return { code = RESULT.FAILED_RULES, reason = REASON.WRONG_ALIGNMENT }
        end
        if not ap_ext_util.check_personality(_personality, event_data.community,
            CONSEQUENCE.AMBUSH_SETUP, cfg.consequence_ambush_setup_personality_min,
            cfg.consequence_ambush_setup_personality_max) then
            return { code = RESULT.FAILED_RULES, reason = REASON.LOW_PERSONALITY }
        end

        -- EVAL: world queries
        local smart = xobject.se(event_data.smart_id)
        if not smart then return { code = RESULT.FAILED_EVAL, reason = REASON.NO_SMART } end

        local squads = ap_core_utils.find_squads_observed(trace, event_data.position, {
            factions = _alignment,
            level_id = event_data.level_id,
            max_distance = ap_core_const.RANGE_SIGNAL,
            max_count = cfg.consequence_ambush_setup_max_squads,
            exclude_at_smart_id = smart.id,
        })
        if #squads == 0 then return { code = RESULT.FAILED_EVAL, reason = REASON.NO_SQUAD } end

        -- ACTION: script squads, record activity
        local moved = {}
        ap_core_debug.observe(trace, PHASE.MOVE_SQUAD, function()
            for i = 1, #squads do
                local res = ap_core_broker.script_squad(squads[i], smart, {
                    rush = cfg.consequence_ambush_setup_rush,
                    on_arrive = CONSEQUENCE.AMBUSH_SETUP,
                    pre_release_gulag = 1800,
                })
                if res.code == RESULT.SUCCESS then moved[#moved + 1] = squads[i] end
            end
            return ap_core_debug.result_squads(moved, { dst_id = smart.id })
        end)
        if #moved == 0 then return { code = RESULT.FAILED_ACTION, reason = REASON.MOVE_FAILED } end

        for i = 1, #moved do
            ap_core_broker.record(moved[i].id, CAUSE.AMBUSH, CONSEQUENCE.AMBUSH_SETUP)
        end

        return ap_core_debug.result_squads(moved, { code = RESULT.SUCCESS, dst_id = smart.id })
    end)
end

function on_game_start()
    ap_core_consumer.register(CONSEQUENCE.AMBUSH_SETUP, {
        event = CAUSE.AMBUSH,
        condition = function() return cfg.consequence_ambush_setup_enabled end,
        on_arrive = _on_arrive,
    }, _handler)
end

Chase (re-script on arrival)

For consequences that pursue a moving target, the arrival handler re-scripts the squad to the target's new location. Each re-script increments a chase counter. The squad gives up after max_chases.

local function _on_arrive(squad, args)
    if not args or not args.target_squad_id then return end
    local chase_count = (args.chase_count or 0) + 1
    if chase_count > cfg.consequence_ambush_setup_max_chases then return end

    local target_squad = xobject.se(args.target_squad_id)
    if not target_squad then return end

    local level_id = xlevel.get_level_id(target_squad)
    if not level_id or xlevel.get_level_id(squad) ~= level_id then return end

    local smart = ap_core_utils.find_smart(target_squad.position, {
        level_id = level_id, max_distance = ap_core_const.RANGE_SIGNAL,
    })
    if not smart then return end

    ap_core_broker.script_squad(squad, smart, {
        rush = cfg.consequence_ambush_setup_rush,
        on_arrive = CONSEQUENCE.AMBUSH_SETUP,
        on_arrive_args = { target_squad_id = args.target_squad_id, chase_count = chase_count },
        pre_release_gulag = 1800,
    })
end

Link arrival to squad: pass on_arrive = CONSEQUENCE.AMBUSH_SETUP in script_squad opts. The broker matches the key to the handler registered via consumer.register(..., { on_arrive = _on_arrive }).

Two Alife Mods Collaborating

scripted_target is the squad control field. Setting it routes the squad to specific_update (direct A->B movement). xsquad provides three primitives:

xsquad.control_squad(squad, smart, rush)   -- acquire: sets scripted_target, clears __lock
xsquad.release_squad(squad)                -- release: clears scripted_target + __lock
xsquad.reassert_target(squad, target)      -- defend: restores scripted_target if overwritten

Both mods check scripted_target before claiming a squad:

-- ModA before scripting:
if se_squad.scripted_target then return end  -- AP (or anyone) has this squad
xsquad.control_squad(squad, smart)

-- AP's PROTECTION gate already does this check automatically.

AP reasserts scripted_target on its squads every 20s. Squads that die or despawn between scans are removed automatically.

For identity (knowing WHO controls a squad), register an ownership filter:

-- In ModA's on_game_start:
ap_core_broker.register_owner("warfare", function(squad)
    return squad.registered_with_warfare == true
end)

There is no shared state or direct imports between mods -- coordination relies entirely on scripted_target and ownership filters.

Listen: Subscribe to Events

Subscribe to cause events via xbus. This requires only xlibs, with no dependency on AlifePlus.

function on_game_start()
    xbus.subscribe("cause:massacre", function(e)
        printf("massacre at %s: %d dead", e.level_id, e.total_deaths)
    end, "my_mod_listener")
end

Available events: cause:massacre, cause:squadkill, cause:basekill, cause:alpha, cause:alphakill, cause:wounded, cause:harvest, cause:stash, cause:area, cause:needs, cause:instincts.

Coordinate: Deep Integration

Direct access to AP domain systems. APIs may change between versions.

Important: script_squad has no inline protection check. Caller must verify with is_protected.

Warfare map tooltip: display AP action

Goal: when your warfare map UI hovers a squad, append what that squad is doing per AlifePlus ("Investigating a Massacre Site", "Guarding an Outpost", "Hunting the Wounded"). Strings are localized; both English and Russian ship with AP. Copy-paste example, warfare author edits only the call site at the bottom:

--- Return localized AP action phrase for a squad, or nil if nothing to show.
--- Graceful no-op when AlifePlus is absent, squad is owned by warfare, or squad has no record.
local function get_ap_action(squad_id)
    if not ap_core_broker or not ap_core_const then return nil end

    local record = ap_core_broker.get_record({ squad_id = squad_id, assigned = true })
    if not record then return nil end

    local info = ap_core_const.CONSEQUENCE_INFO[record.consequence]
    if not info then return nil end

    local text = game.translate_string(info.action_key)
    if not text or text == info.action_key or text == "" then return nil end
    return text
end

-- Call site (warfare's tooltip builder, wherever you assemble the hover text):
local ap_action = get_ap_action(squad.id)
if ap_action then
    tooltip_text = tooltip_text .. "\n" .. ap_action
end

Notes for warfare authors:

• Call get_record fresh on every render tick. Records mutate as squads move between consequences.
• ap_core_const.CONSEQUENCE_INFO is a static const table -- read it directly, don't cache.
• Each entry has action_key (full phrase shown to the player) and name_key (short caption for config / debug). Pick whichever fits your UI.
• Locale switch (English/Russian) works automatically because the resolve happens at render time via game.translate_string.
• A nil return means the squad has no recent AP activity (or is warfare-owned). Render nothing.
• Squads warfare owns are already excluded from AP via the ownership registry (register_owner("warfare", ...) is registered by default in ap_core_compat). They never enter the pipeline, never get a record, so get_record returns nil and you render nothing. No additional filtering needed on warfare's side.

Typical action outputs (EN): "Investigating a Massacre Site", "Scavenging a Massacre Site", "Reinforcing Attacked Base", "Evacuating Attacked Base", "Hunting the Wounded", "Guarding an Outpost", "Out Exploring", "Heading to a Campfire to Rest", "Restocking at Trader", "Harvesting Artefacts". 36 entries total, one per AP consequence. Full map: ap_core_const.CONSEQUENCE_INFO keys.

Warfare ownership: suppress AP for warfare-owned squads

If warfare overrides the default filter (to scope warfare ownership more precisely than squad.registered_with_warfare), re-register on on_game_start:

-- In warfare's on_game_start:
ap_core_broker.register_owner("warfare", function(squad)
    return squad.my_warfare_flag == true  -- whatever warfare actually uses
end)

register_owner replaces the existing filter on name match. This lets warfare scope ownership natively and override AP's default proxy. After registration, AP excludes matching squads at four layers (producer gate, cause predicate, find_squads, squad scripting), so warfare-owned squads are fully invisible to AP.

Checklist: Adding a New Cause + Consequence

1. Add CAUSE.X to ap_core_const CAUSE table
2. Add CONSEQUENCE.X_VERB to ap_core_const CONSEQUENCE table
3. Add MCM defaults to ap_core_mcm.defaults
4. Create ap_ext_cause_x.script with predicate, register in on_game_start
5. Create ap_ext_consequence_x_verb.script with handler, register in on_game_start
6. Add PDA messages to ap_ext_messages if needed
7. Add MCM UI entries to ap_core_mcm menu builder
8. Run validator: stalker-manager.sh validate

Full documentation: integration-guide.md and architecture.md.

Architecture

Problem

Most alife mods for Anomaly hook engine callbacks independently, iterate over squads on a timer, implement their own rate limiting, 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. The codebase is split into core (ap_core_*) and ext (ap_ext_*). Core never imports ext. All domain logic reaches the framework through registered function references.

• xlibs provides invariants: event bus (publish/subscribe), squad safety (protection checks via is_protected composite guard, scripting, release), smart terrain queries, entity resolution, and shared utilities (logging, profiling, time, math)
• AlifePlus core provides the pipeline: a 4-gate radiant dispatcher and 3-gate reactive dispatcher, cause/consequence routing via xbus, a personality gate (per-faction trait-based behavioral filtering), an ownership registry (register_owner/get_owner -- mods declare which squads they control), squad lifecycle management (scripting with TTL, arrival detection, post-arrival wait, automatic unscript), and multi-layer rate limiting (pacer, Bresenham ratio, per-cause/consequence budgets, global radiant consequence counter)
• Mods register domain logic: a cause predicate and a consequence handler. The framework handles gates, protection, rate limiting, tracing, arrival, and cleanup.

What the framework provides

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

Pipeline (radiant)

Radiant causes fire on squad_on_update (sole radiant source). Four gates, each either passes or rejects. Reactive uses PACER (per-callback token bucket) + RATIO + EVAL only (protection handled downstream in causes and consequences).

Potential integrations

Examples of how existing alife mods could use the framework instead of reimplementing squad control:

Full documentation: integration-guide.md and architecture.md.