The Game Loop

The Game Loop

TalesMUD runs multiple concurrent goroutines to manage game state. Understanding the update cycles helps you reason about when scripts fire and how frequently game state changes.

Goroutines per Player Connection

Each WebSocket connection spawns four goroutines:

Goroutine	Purpose
Message Receiver	Reads incoming WebSocket messages from the client
Game Loop	Processes commands and events for this connection
Broadcast Handler	Listens for room/global broadcasts and forwards to client
Timeout Handler	Disconnects idle sessions after a configurable period

Server-Wide Update Cycles

Independent of player connections, the game engine runs periodic update ticks:

Cycle	Interval	What It Does
Room Updates	10 seconds	Fires room.update events, runs room tick scripts
NPC Updates	10 seconds	Updates NPC AI state, handles idle behavior
Spawner Updates	5 seconds	Checks spawners, spawns NPCs if below max count
Combat Updates	2 seconds	Resolves pending combat rounds, applies status effects

Message Processing

The game loop processes two categories of input:

Player Messages

Commands typed by players:

1. Client sends message over WebSocket
2. Receiver goroutine reads it
3. Message queued to the game loop
4. CommandProcessor dispatches to appropriate handler
5. Handler executes game logic, produces output messages
6. Output routed to appropriate audience

System Events

Events from the server itself (NPC deaths, spawns, combat ticks):

1. Event generated by update cycle or another handler
2. Queued as a synthetic message
3. Processed by game loop in same pipeline as player commands

Combat Loop Detail

The combat update runs every 2 seconds. When a combat instance is active:

1. Check for disconnected players (auto-flee)
2. Apply status effect ticks (DoT damage, HoT healing)
3. Reduce cooldowns by 1 round for each combatant
4. Auto-attack: each combatant attacks their target
5. Check for defeat conditions (HP ≤ 0)
6. If combat ends: distribute XP and loot, send resolution messages
7. Update character state in the database

Spawner Cycle

Every 5 seconds, each room’s spawners are checked:

1. Count current NPC instances in the room for this template
2. If count < maxCount AND last_spawn + respawn_time has elapsed
3. Create a new NPC instance (with a unique instance ID)
4. Place the NPC in the room
5. Notify players in the room

Thread Safety

WebSocket writes are protected by a mutex. All game state mutations go through the service layer which handles SQLite transactions. The Lua VM pool ensures safe concurrent script execution (each script gets its own VM state from the pool).

Next Steps

• Combat System — How combat rounds resolve
• Message System — How messages reach players
• Scripting Event Hooks — Reacting to game events