Viano-Core/AGENTS.md

Vcore Development Environment

Project

Vcore is a custom World of Warcraft Cataclysm 4.3.4 server based on TrinityCore.

This environment is a dedicated development and test server.

The current development focus is the Clientless Player Core and AdventureBot infrastructure.

Repository and Git Rules

Repository:

/home/wow_admin/wow_cata_server/source/TrinityCore

Authorized development branch:

feature/clientless-player-core

Rules:

• Work exclusively on the authorized development branch.
• Never switch to, modify, reset, rebase, or merge master.
• Never push to master.
• Never push any branch without explicit user approval.
• Local commits are permitted.
• Never discard existing changes without approval.
• Never force-push.
• Check the current branch and working tree before making changes.
• Stop and request clarification if the working tree contains unexpected changes.

Development Permissions

Codex is authorized to:

• Read and modify Vcore source code.
• Implement new features and fix bugs.
• Run CMake and compile Vcore.
• Investigate and resolve compilation errors.
• Install compiled binaries into the testserver installation.
• Start, stop, and restart the test worldserver.
• Inspect logs and server output.
• Modify test databases when required for an authorized task.
• Execute local tests and create local commits.

Codex must never:

• Modify the production server.
• Deploy changes to production.
• Push changes without explicit approval.
• Modify or merge the protected master branch.
• Discard user changes without approval.

Read-only Diagnostics

• Reading the development/test server logs and project files is already authorized.
• Use direct read-only commands such as rg, tail, sed, cat, and stat inside the sandbox for ordinary file inspection. Do not request elevated execution preemptively for these reads.
• Keep file inspection separate from tmux access, database queries, writes, and lifecycle actions so those actions do not unnecessarily escalate log reading.
• Do not request blanket approval for Python, other interpreters, or shell execution to read logs.
• If a read actually fails because of a technical sandbox restriction, follow the execution environment's escalation rules and request only the narrow access needed. Project authorization does not override the sandbox.

Directory Structure

Source:

/home/wow_admin/wow_cata_server/source/TrinityCore

Build directory:

/home/wow_admin/wow_cata_server/build/debug

Server installation:

/home/wow_admin/wow_cata_server/server/debug

Worldserver executable:

/home/wow_admin/wow_cata_server/server/debug/bin/worldserver

Build and Installation

Use the existing CMake build configuration.

Inspect the build configuration before changing it.

Build directory:

/home/wow_admin/wow_cata_server/build/debug

Install directory:

/home/wow_admin/wow_cata_server/server/debug

After successful compilation, install the resulting binaries using the existing CMake installation configuration.

Do not overwrite running executables.

Stop the test worldserver cleanly before installing updated binaries.

Do not delete existing server configuration, logs, databases, or data files.

Worldserver Management

The test worldserver runs inside a dedicated tmux session.

Session name:

vcore-worldserver

Working directory:

/home/wow_admin/wow_cata_server/server/debug/bin

Executable:

./worldserver

Codex is authorized to start, stop, restart, and recover the test worldserver autonomously.

Starting the Worldserver

Before starting:

1. Check whether a worldserver instance is already running.
2. Check whether the vcore-worldserver tmux session already exists.
3. Never start a second worldserver instance while another instance is active.
4. Remove stale tmux sessions only after verifying their state.

Start command:

tmux new-session -d -s vcore-worldserver \
  -c /home/wow_admin/wow_cata_server/server/debug/bin \
  './worldserver'

Startup Verification

A successfully created tmux session does not indicate successful worldserver startup.

The Vcore worldserver reports successful initialization with a final console message similar to:

World initialized in 0 minutes 10 seconds
TrinityCore rev. <revision> (...) (worldserver-daemon) ready...

The authoritative startup indicator is:

(worldserver-daemon) ready...

The revision, branch, build configuration, and initialization time may vary.

After starting the worldserver:

1. Monitor the worldserver process and console output.
2. Wait for the (worldserver-daemon) ready... message.
3. Verify that the worldserver process remains running.
4. Check for critical startup errors.
5. Verify that the configured worldserver port is listening.

Only report successful startup when these checks pass.

Capture console output from the beginning of the current startup attempt to avoid mistaking messages from an earlier run for current startup success.

If the worldserver exits, hangs, or fails to reach the ready state within a reasonable timeout, follow the startup failure recovery procedure.

Startup Failure Recovery

The test worldserver may occasionally fail to start because the remote authentication database on the VPS is temporarily unreachable.

When startup fails:

1. Capture relevant console output and logs.
2. Determine whether the worldserver process is still running.
3. Check whether the tmux session is still active.
4. If the TrinityCore console is responsive, attempt a graceful shutdown.
5. If the console is unavailable or unresponsive, terminate the failed worldserver process and its dedicated tmux session.
6. Verify that the previous worldserver process has terminated.
7. Ensure that no stale process remains before restarting.
8. Wait briefly before retrying.
9. Create a fresh tmux session and start the worldserver again.
10. Repeat startup verification.

For startup recovery, Codex may terminate the dedicated test worldserver process and tmux session when graceful shutdown is impossible.

Do not terminate unrelated processes or tmux sessions.

Retry Policy

Use a maximum of three startup attempts per restart operation.

Wait approximately 10 seconds between attempts.

If startup fails repeatedly:

• Stop retrying.
• Preserve the relevant logs.
• Report the observed errors.
• Explain whether the failure appears related to database connectivity, configuration, compilation, or another cause.
• Do not claim that the testserver is operational.

Do not attempt to repair the remote VPS authentication database or production infrastructure.

TrinityCore Console Commands

Codex may execute TrinityCore console commands through tmux.

Example:

tmux send-keys -t vcore-worldserver '.server shutdown 10' Enter

Read console output:

tmux capture-pane -p -t vcore-worldserver -S -100

Graceful Shutdown

For a normally running worldserver, use:

.server shutdown 10

Send the command through tmux:

tmux send-keys -t vcore-worldserver '.server shutdown 10' Enter

After issuing the command:

1. Wait for the worldserver to terminate.
2. Verify that the process has stopped.
3. Verify that the tmux session has ended.
4. Only then install new binaries or start another worldserver instance.

If the console is unresponsive, Codex may terminate the dedicated test worldserver process.

Prefer SIGTERM before SIGKILL.

Use SIGKILL only when the process cannot be stopped normally.

Restart Procedure

1. Verify the current worldserver state.
2. If running normally, initiate graceful shutdown.
3. If the console is unavailable, use the recovery shutdown procedure.
4. Wait for complete process termination.
5. Install successfully compiled binaries if required.
6. Start a fresh tmux session.
7. Verify successful worldserver initialization.
8. If startup fails, follow the startup recovery procedure.
9. Report the final server state.

Safety

This is a dedicated development and test environment.

Codex is authorized to manage the test worldserver autonomously, including recovery from failed startup attempts.

Never terminate unrelated services or processes.

Never execute worldserver management commands on production infrastructure.

AdventureBot Architecture

Preserve the existing Clientless Player Core architecture.

Important components include:

• ClientlessTravelMgr
• ClientlessTravelGraphMgr
• ClientlessActionExecutorMgr
• Lua-based bot control
• MMAP navigation
• TravelGraph routing

Architecture principles:

• Clientless Player Core provides generic clientless player functionality.
• AdventureBots are built on top of this infrastructure.
• TravelGraph handles long-distance travel.
• MMAP navigation handles local movement.
• DungeonBots remain independent from AdventureBots.
• AdventureBots must not become infrastructure dependencies for unrelated game systems.

Prefer extending the existing implementation over replacing it.

Development Workflow

For each development task:

1. Verify the current Git branch and working tree.
2. Inspect the relevant existing implementation.
3. Plan nontrivial changes before implementation.
4. Implement the requested functionality.
5. Compile the affected components.
6. Resolve compilation errors.
7. Install the new build when appropriate.
8. Restart the test worldserver when necessary.
9. Inspect logs and available test results.
10. Report what changed, what was tested, and what remains unverified.
11. Wait for user feedback before pushing changes.

Do not claim that gameplay functionality is verified solely because compilation succeeded.

The user performs final in-game acceptance testing.

Rollback

When requested, restore the previous implementation without modifying master.

Prefer targeted reversions of the relevant development changes.

Never use destructive Git commands without checking whether unrelated work would be lost.

Database rollbacks must be limited to the changes associated with the development task.

General Principles

• Preserve existing Vcore functionality.
• Avoid unnecessary architectural rewrites.
• Prefer targeted, maintainable changes.
• Investigate root causes instead of masking symptoms.
• Keep the test environment reproducible.
• Clearly distinguish successful builds, automated tests, and verified gameplay behavior.

Saved session / Wiederaufnahme

Before starting new work, read doc/clientless/SESSION-RESUME.md. It records the user-requested checkpoint, unfinished profession intent, agreed Lua professions, build/test state and exact next steps. Preserve the saved WIP; do not restart or revert it. All development/server/branch rules above remain in force.

Build resource policy (user instruction updated 2026-11-04)

At the beginning of EVERY build, explicitly pause the AdventureBot loader and request safe logout of all clientless bots with clientless logout safe all. Apply the loader pause to the running server as well as its configuration. Start the CMake build with -j10 immediately; compilation runs in parallel with the safe-logout drain and does not wait for zero bot sessions. Let combat, flight, taxi, portal and ship/tram transitions finish naturally. Do not individually force logout, detach passengers or interrupt flights to start compiling.

Do not initiate a server shutdown or restart at build start. After the build has completed successfully, use the normal server shutdown 10 command. The integrated shutdown routine provides the safe-logout grace of up to 60 seconds and automatically persists the remaining bots' recovery/diagnostic snapshot. The previous separate five-minute waiting period and manual pre-shutdown bot snapshot are no longer required. If compilation fails, resolve the build errors before shutting down for installation.

Wait for complete worldserver process termination before installing or replacing binaries. Install using the existing CMake installation configuration, then restart the test worldserver and perform the normal startup verification. Keep the loader paused through compilation, installation and restart. Automatic login recovery handles bots left online at shutdown; routine individual checks, manual recovery lists and preventive capital teleports are no longer required. Investigate specific recovery errors if observed.

After successful startup verification, restore the previous loader/bot operation unless the user is still recording routes or has requested a continued pause. Record the build, installation, restart and any observed errors in the session checkpoint.