# 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:

```bash
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:

```text
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:

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

Read console output:

```bash
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:

```bash
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.