NPC Simulator: 100 NPCs, One Dashboard, and a Suspicious Amount of Cowbell.

The briefing was simple: deploy a small simulation, demonstrate command flow, and do not touch production.

Thirty seconds later, the scouts were wandering, the hunters were pursuing stale information, and sixty followers were heading toward the average location of management.

Finally. A realistic organizational model.

MatrixSwarm’s npc_simulator is a compact, rule-based simulation with a Phoenix gameboard. It gives you something visible to control while learning how a swarm receives commands and returns signed state updates.

There is a player marker, three kinds of NPC, several temporary effects, and a Cowbell button whose strategic importance is difficult to overstate.

This walkthrough uses the current implementation as it exists: one agent, a 20×20 board, 100 NPC records, and one viewer session. There is no language-model call behind each dot and no need to stage a real outage to make the screen interesting.

One agent, one crowded little world

The default population is:

Character	Board appearance	Assignment
Player	Green @	Move automatically around the board
10 scouts	Yellow NPC markers	Wander and report a nearby player position
30 hunters	Red NPC markers	Pursue the shared last-seen player position
60 followers	Cyan NPC markers	Move toward the hunters’ average position

Those are 100 entities maintained by one MatrixSwarm agent, not 100 independently deployed swarm agents. The distinction matters when explaining the architecture—or when someone begins multiplying an imaginary per-NPC API bill.

The player is automatic too. This panel does not provide WASD movement. You influence the exercise with its command buttons while the player jitters around the grid.

The world is deliberately small enough to inspect. You can see the difference between “the button changed something” and “we clicked it and everyone nodded because the demo was nearly over.”

Install, assemble, launch—then release the dots

If MatrixOS is not already on the target, add and test the target’s SSH connection in Phoenix’s Registry, including its trusted host fingerprint. Open Railgun’s Install MatrixOS flow and select Local Full Install or Install from GitHub. For a fresh setup, use Create new venv with the installer’s required root or passwordless-sudo access.

Open Deploy → Swarm Workspaces and create a workspace or edit an existing one. Keep the Matrix root and add:

• npc_simulator;
• matrix_https for command ingress;
• matrix_websocket for the return stream;
• log_streamer for Agent Logs and troubleshooting.

Keep the NPC agent’s default board/population settings and supplied panel/command declarations. Resolve packet signing and the connection requirements. The return path uses the RPC relay role, normally hive.rpc.

Save and Deploy through Railgun with the target SSH record, universe, label, and runtime account. Railgun carries the sealed boot envelope over pinned SSH to MatrixD; MatrixD decrypts it in memory and launches the swarm. Connect Phoenix and open NPC Panel.

The gameboard is the interface for this exercise. Start with its controls and the supplied defaults; you do not need a separate NPC configuration panel.

Briefing over. The yellow dots have already wandered away from it.

What each group actually knows

Scouts: reconnaissance with questionable cardio

Scouts choose a random cardinal move or stay put. Under ordinary conditions, a scout detects the player when their Manhattan distance is less than four—count horizontal plus vertical grid steps, not a straight diagonal line.

A detection updates a shared last-seen player coordinate. That is the information the hunters use.

The scout has not built a belief model, consulted a map, or sent an emotionally complicated radio message. It saw something close enough and updated a coordinate. Admirably concise field reporting.

Hunters: an address and considerable confidence

Hunters move toward that shared last-seen coordinate. Their movement chooses the horizontal direction more often than the vertical direction. Without a target, they have nothing to pursue.

The distinction between the player’s current position and the last-seen position is the interesting part. A hunter can be faithfully following information that is already old. The player continues moving; scouts may refresh the sighting.

This is not predictive pathfinding. It is a small, visible example of agents acting on shared, imperfect information. Anyone who has followed an outdated incident ticket will recognize the terrain.

Followers: the center of the committee

Followers move toward the integer average of the hunters’ coordinates. They are following the hunters as a group, rather than independently tracking the player.

That makes the behavior legible: move the hunting group and the following group tends to respond. The resulting crowd is simple enough to reason about while still producing a lively board.

If this reminds you of a meeting where nobody knows the objective but everyone knows where the managers are standing, please submit your findings through the proper channel.

The command desk

Button	Current effect
Start	Begin this session’s state stream and simulation stepping
Stop	Stop this session’s stream
Hunt	Set the shared target to the player’s current position at that moment
Scatter	Override NPC movement with random movement for three simulation ticks
Ping	Increase scout detection distance to less than six for two ticks
Shield	Reverse hunter pursuit away from the remembered target for five ticks
Lock	Freeze NPC movement for five ticks; the player still moves
Cowbell	Play a local sound if the sound asset and audio output are available

A tick here means a simulation step. The current stream loop uses a fixed interval of about 1.5 seconds, with processing and transport adding time. These are short-lived effects in a deliberately low-rate demo, not promises of frame-perfect timing.

The palette’s tick_interval_sec setting is not currently what drives that stream cadence. Changing it does not give you a 60 FPS tactical command center.

Cowbell does not send an agent command or alter the simulation. It lives in the Phoenix panel. Sometimes the correct architectural boundary is between distributed state and a deeply necessary percussion instrument.

A field exercise you can narrate in five minutes

First, press Start and watch a few updates. Identify the player, scouts, hunters, and followers. The exact arrangement varies because initial placement and movement are random. Do not expect someone else’s board to match yours.

Next, press Hunt. This supplies an immediate target using the player’s position at that instant. Watch the hunters respond. It does not permanently attach them to a live GPS feed; later scout sightings can update the remembered position.

Press Scatter and let it run its three ticks. The NPCs temporarily abandon their role movement. After the effect expires, normal role behavior returns.

Scatter uses a different movement path from ordinary movement and can place multiple NPCs in the same cell. The board can show a count where characters overlap. A number on a crowded tile is not necessarily a rendering failure. Sometimes everyone really did choose the same exit.

Try Ping. For two ticks, scouts can detect the player from farther away. The effect changes their detection threshold; it does not guarantee a new sighting if every scout is still too far from the player.

Try Shield when hunters have a target. For five ticks, hunters reverse their pursuit direction relative to the remembered target. This affects hunters. It is not an invulnerability system, and it does not turn every NPC into a fleeing civilian.

Try Lock. NPC movement freezes for five ticks, while the player continues moving. The other effect counters can continue counting down too, so a locked board does not preserve every temporary effect in amber.

Press Cowbell, purely for scientific completeness. If your audio setup obliges, morale will become measurable in decibels.

Finally, press Stop. Use the actual Stop control when finishing the exercise. Hiding or leaving the panel is not a reliable substitute for stopping its stream.

The point is to connect each button to an observable change. You have now exercised commands, state updates, short-lived policy changes, and session lifecycle without persuading a production database to provide the entertainment.

What travels through the swarm

At a high level, the control loop is:

Phoenix NPC Panel
    → command ingress
    → NPC Simulator command handler
    → simulation step and signed state frame
    → RPC/WebSocket return path
    → Phoenix board update

The simulation owns the positions and temporary-effect counters. Phoenix presents the controls and renders returned state. The panel consumes verified callbacks; signing requirements are part of the deployment, not an optional flourish around the demonstration.

The board keeps a small frame queue and uses the latest frame instead of faithfully animating every stale update. That is sensible for a live status display: when the world has moved on, you usually want to see where it is now.

It is not an event replay system, a durable simulation log, or a guarantee that every intermediate move will be drawn on screen.

Likewise, log_streamer is useful here for the agents’ diagnostic logs. The NPC board’s structured state frames travel through its own callback path. Agent Logs and the gameboard are complementary views, not interchangeable streams.

The important prototype boundary: use one viewer

The current agent holds one shared world. Each active viewer session starts its own stream loop, and those loops advance that same world.

Consequently, opening multiple viewers is not merely adding spectators. It can change stepping speed and interleave state updates. This walkthrough deliberately uses one viewer session.

With no active, healthy stream loop, this implementation is not running an independent background simulation clock. Start and Stop therefore matter to both observation and progression. Stop affects your session; another active viewer can keep advancing the world.

The stream also depends on an available RPC relay and a live session connection indicator. A missing or stale connection indicator ends the stream; reconnect and start again when the connection is healthy.

Stop followed by Start resumes the current in-memory world. It is not a reset button. Restarting the agent creates a new randomized world; this demo does not persist its simulation state.

These details make it a useful teaching prototype. They also explain why we are calling it a small simulation exercise rather than announcing an MMO and making the networking team quietly leave the room.

Keep the supplied dimensions for now

The current Phoenix board is built around a 20×20 grid. The agent’s default population is ten scouts, thirty hunters, and sixty followers.

Keep those defaults for this walkthrough. Lower population values slice that role list rather than proportionally scaling the three groups, and the current list does not create arbitrary numbers above 100. Making the grid too small for its unique initial placements can also prevent initialization from completing.

Changing a number in configuration is not automatically the same thing as supporting every number. This principle has prevented at least several extremely awkward demos.

There is no combat system, health bar, score, win condition, navmesh, or language-model reasoning in these NPC rules. You can inspect their behavior as code, follow it visually, and use the exercise to understand the transport around it.

That is already plenty of work for one hundred dots.

When the board refuses to perform

Symptom	First useful check
No frames after Start	Connection, command roles, the hive.rpc relay, and required signing assignments
Stream stops unexpectedly	Session connectivity and heartbeat freshness; reconnect, then Start
NPCs freeze but the player moves	Lock may still be active
Everything looks stale	Agent Logs and the return path; do not diagnose transport from one frozen picture
Player marker seems missing	Overlapping NPCs can obscure its cell
Simulation speeds up with another viewer	Both sessions may be advancing the shared world
Cowbell is silent	Local sound asset and audio output, rather than the remote agent

If you extend the demo, a useful next engineering step would be separating simulation time from viewer streams, then making each viewer a read-only consumer of the same world clock. A seeded random generator would also make repeatable demonstrations easier. Those are potential improvements, not features claimed by this walkthrough.

For now, you have a small, interactive place to learn the swarm’s control loop. Commands have visible consequences. Return traffic has a purpose you can point at. The agents’ logs help explain a stalled demonstration.

And if somebody asks what business value the Cowbell provides, tell them the distributed system has achieved eventual enthusiasm.

Victory Always. Keep the hunters informed and the briefing short.

---

🌐 Links & Resources:

Try MatrixSwarm: https://matrixswarm.com

Join the Community / Discord: https://discord.gg/2USbWVBVV

Download Server: https://github.com/matrixswarm/matrixswarm

Youtube: https://www.youtube.com/channel/UCMjiY4_-W2KP5fHXO0eC2ug