SDK Documentation

// Attach WarweaverManager to a GameObject in your scene
// Configure in Inspector:
//   Lockfile Path: "lockfile.json" (relative to StreamingAssets)
//   Target Ticks Per Second: 5

using Warweaver.UnityAdapter;

public class MyGameController : MonoBehaviour
{
    private WarweaverManager _manager;
    private WarweaverAdapter _adapter;

    void Start()
    {
        _manager = FindObjectOfType<WarweaverManager>();
        _adapter = _manager.Adapter;

        // Define your schema (before simulation starts)
        var hpHandle = _adapter.CreateAttribute("HP", 0f, 100f, 100f);

        // Start simulation
        _manager.StartSimulation();
    }
}

// Start the simulation loop (runs in background)
_manager.StartSimulation();

// Stop the simulation
_manager.StopSimulation();

// Step one tick (for frame-by-frame control)
_manager.StepSimulation();

// Reset to initial state
_manager.ResetSimulation();
_manager.ResetSimulation(newSeed: 12345); // With new seed

// Create attributes during setup
var hpHandle = _adapter.CreateAttribute("HP", min: 0f, max: 100f, defaultValue: 100f);
var strengthHandle = _adapter.CreateAttribute("Strength", 1f, 100f, 10f);

int warriorId = _adapter.CreateArchetype("Warrior", new ArchetypeConfig
{
    RequiredAttributes = new[] { hpHandle, strengthHandle },
    AllowedOperators = new[] { attackOpId, chargeOpId }
});

int priestId = _adapter.CreateArchetype("Priest", new ArchetypeConfig
{
    RequiredAttributes = new[] { hpHandle, mpHandle },
    AllowedOperators = new[] { healOpId, blessOpId }
});

int noiseSignalId = _adapter.CreateSignal("Noise");
int dangerSignalId = _adapter.CreateSignal("Danger");

int attackOpId = _adapter.CreateOperator("Action_Attack");
int healOpId = _adapter.CreateOperator("Action_Heal");
int fleeOpId = _adapter.CreateOperator("Action_Flee");

// 1. Enqueue the spawn command
long commandId = _adapter.EnqueueSpawnAgent(
    archetypeId: warriorId,
    position: new Vector2(10f, 20f),
    factionId: 1
);

// 2. Step the simulation to execute
_manager.Host.Step();

// 3. Get the spawned agent ID
ushort agentId = _adapter.WaitForSpawnAck(commandId);

// Auto-steps the simulation (use with caution in deterministic scenarios)
ushort agentId = _adapter.SpawnAgent(warriorId, new Vector2(10f, 20f), factionId: 1);

// Get a single agent
var agent = _adapter.GetAgent(agentId);
var position = agent.GetPosition();
var hp = agent.GetAttribute(hpHandle);

// Get all agents
var allAgents = _adapter.GetAllAgents();
foreach (var a in allAgents)
{
    // Process each agent
}

// Set HP for an agent
_adapter.SetAttribute(agentId, hpHandle, 75f);

// Get current HP (queries CurrentTick)
float hp = _adapter.GetAttribute(agentId, hpHandle);

// Query a specific historical tick
float hpAtTick5 = _adapter.GetAttribute(agentId, hpHandle, tick: 5);

// Get agents whose attributes changed this tick
ushort[] dirtyAgents = _adapter.GetDirtyAgentIds();

foreach (var id in dirtyAgents)
{
    // Update only these GameObjects
    float hp = _adapter.GetAttribute(id, hpHandle);
    UpdateHealthBar(id, hp);
}

void Update()
{
    // Swap buffers at frame start
    _adapter.SwapTelemetryBuffers();

    // Read from front buffer (stable until next swap)
    var snapshot = _adapter.GetTelemetrySnapshot();

    for (int i = 0; i < snapshot.AgentCount; i++)
    {
        var agent = snapshot.Agents[i];
        UpdateAgentPosition(agent.AgentId, agent.X, agent.Y);
    }
}

// Get direct NativeArray views (no allocation, no copy)
NativeArray<float> positionsX = _adapter.GetPositionXView();
NativeArray<float> positionsY = _adapter.GetPositionYView();
NativeArray<int> factionIds = _adapter.GetFactionIdView();
NativeArray<int> currentActions = _adapter.GetCurrentActionView();

// Use in Burst job
[BurstCompile]
struct UpdatePositionsJob : IJobParallelFor
{
    [ReadOnly] public NativeArray<float> PositionsX;
    [ReadOnly] public NativeArray<float> PositionsY;
    public NativeArray<float3> Transforms;

    public void Execute(int i)
    {
        Transforms[i] = new float3(PositionsX[i], 0f, PositionsY[i]);
    }
}

var version = _adapter.GetBufferVersion();
// ... use views ...

// Check if buffer was resized (views invalidated)
if (!_adapter.IsViewValid(version))
{
    // Re-acquire views
}

var activeSet = _adapter.GetActiveSet();

// Only update GameObjects for active agents
foreach (var agentId in activeSet.ActiveAgentIds)
{
    // Full GameObject update (position, animation, effects)
}

// Background agents get minimal updates
foreach (var agentId in activeSet.BackgroundAgentIds)
{
    // Position only, no animation
}

var commands = new AgentCommandOutput[100];
int count = _adapter.GetAgentCommands(out commands);

for (int i = 0; i < count; i++)
{
    var cmd = commands[i];
    if (cmd.HasActiveOperator)
    {
        TriggerAnimation(cmd.AgentId, cmd.ActiveOperatorId);

        if (cmd.HasTargetEntity)
        {
            PlayAttackEffect(cmd.AgentId, cmd.TargetAgentId);
        }
    }
}

// From Unity's line-of-sight system
int[] visibleEntities = GetVisibleEntitiesFromRaycasts(agentId);

// Inject into simulation
_adapter.UpdatePerception(agentId, visibleEntities);

// Get all observations for an agent
var observations = _adapter.GetObservations(agentId);

foreach (var obs in observations)
{
    Debug.Log($"Agent {agentId} observed entity {obs.SubjectId}");
}

// Or just get visible entities
int[] visible = _adapter.GetVisibleEntities(agentId);

long commandId = _adapter.InjectSignal(
    signalId: noiseSignalId,
    position: new System.Numerics.Vector3(50f, 0f, 50f),
    radius: 30f,
    duration: 60  // ticks
);

void Update()
{
    Intent[] intents = _manager.Host.PollIntents();

    foreach (var intent in intents)
    {
        switch (intent.Kind)
        {
            case IntentKind.MoveTo:
                var target = intent.Payload.MoveTo;
                ExecuteMovement(intent.AgentId, target.X, target.Y, intent.IntentId);
                break;

            case IntentKind.UseAction:
                var action = intent.Payload.UseAction;
                ExecuteAction(intent.AgentId, action, intent.IntentId);
                break;
        }
    }
}

// Success
_manager.Host.ReportIntentResult(intentId, IntentResultCode.Success);

// Failed
_manager.Host.ReportIntentResult(intentId, IntentResultCode.Failed,
    reason: new IntentResultReason { Message = "Path blocked" });

// Blocked (with cooldown)
_manager.Host.ReportIntentResult(intentId, IntentResultCode.Blocked,
    reason: new IntentResultReason { CooldownTicks = 30 });

var affordanceSet = new AffordanceSet
{
    AgentId = agentId,
    Tick = _manager.CurrentTick,
    Affordances = new[]
    {
        new Affordance("Action_Fireball", isAvailable: false, blockReason: "On cooldown"),
        new Affordance("Action_Heal", isAvailable: true)
    }
};

_manager.Host.PushAffordances(agentId, affordanceSet);

// Get agents within radius
ushort[] nearby = _manager.Host.GetAgentsInRadius(50f, 50f, radius: 20f);

// Get nearest agent
ushort? nearest = _manager.Host.GetNearestAgent(50f, 50f);

// Check if agent exists
bool isValid = _manager.Host.IsValidAgentId(agentId);

// Check if queries are allowed
if (_manager.Host.CanQuery())
{
    // Safe to query
}

// Schema setup
var reputationHandle = _adapter.CreateAttribute("Reputation", -100f, 100f, 0f);
var favorHandle = _adapter.CreateAttribute("Favor", 0f, 100f, 50f);
int tradeSignalId = _adapter.CreateSignal("TradeCompleted");

// Later: inject a trade event when player buys from the merchant
_adapter.InjectSignal(
    signalId: tradeSignalId,
    position: merchantPosition,
    radius: 0f,    // only this merchant perceives it
    duration: 1    // single tick
);

// Read the merchant's updated favor via telemetry
float favor = _adapter.GetAttribute(merchantId, favorHandle);
float priceMultiplier = Mathf.Lerp(1.5f, 0.7f, favor / 100f);
UpdateShopUI(priceMultiplier);

// When the scout's perception detects an enemy
int dangerSignalId = _adapter.CreateSignal("Danger");

// Inject a danger signal with large radius
_adapter.InjectSignal(
    signalId: dangerSignalId,
    position: enemyPosition,
    radius: 100f,   // all villagers within 100 units perceive it
    duration: 120    // persists for 4 seconds at 30 TPS
);

// No script tells villagers to flee.
// Each agent's BDI/GOAP planner evaluates the danger signal
// against their own goals, personality, and current state.
// Warriors might charge. Civilians might flee. Priests might heal.
// The emergence IS the game.

// You noticed Agent #47 attacked an ally at tick 1,234
// Step 1: Reset with the same seed
_manager.ResetSimulation(originalSeed);

// Step 2: Advance to the tick before the decision
for (int t = 0; t < 1233; t++)
    _manager.StepSimulation();

// Step 3: Step one tick and inspect the reasoning trace
_manager.StepSimulation();

// Now examine what Agent #47 saw and decided
var observations = _adapter.GetObservations(47);
var commands = _adapter.GetAgentCommands(out var cmdBuffer);

// The trace reveals: Agent #47 perceived the ally as hostile
// because a "Betrayal" signal was injected at tick 1,200.
// Determinism means this will reproduce every single time.