CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Read AGENTS.md in the repository root before doing anything else. Its "Non-negotiable rules" section is binding and takes precedence over everything in this file. It is the single source of truth for those rules — they are not duplicated here, so go read them.

Project Overview

MafiaHub Framework is a C++ framework for building multiplayer game modifications. It provides networking, ECS (Entity Component System), scripting, GUI, and other essential components for synchronized multiplayer experiences.

Build Commands

ALWAYS build from the CLI via builds\build.bat <target> <arch>. This is the single supported way to build any target in this repo from the command line. It loads the matching vcvars*.bat and drives the canonical pre-configured build tree. Never invoke cmake --build directly and never create ad-hoc/temporary build directories. See the Mandatory Windows build rule below.

macOS/Linux:

cmake -B build              # Configure
cmake --build build         # Build
cmake --build build --target RunFrameworkTests  # Run tests

Windows:

builds\build.bat <target> 64

For HogwartsMP, build the debug client and server with:

builds\build.bat HogwartsMPClient 64
builds\build.bat HogwartsMPServer 64

Mandatory Windows build rule: Always use builds\build.bat. Its canonical 64-bit debug build directory is builds\build-64, and its artifacts belong in that build's debug output. Never create or use ad-hoc CMake build directories (including any codex-*, verify, smoke, or temporary build folder) for repository builds. Do not invoke cmake --build directly when the build script can build the requested target. If the canonical build is broken, diagnose or repair it rather than creating a parallel build tree.

Or use Visual Studio 2022 with CMake tools installed and open the repository folder for automatic setup.

Project Structure

• code/framework/ - Core framework source code split into three libraries:
  • Framework - Shared utilities and core systems
  • FrameworkClient - Client-specific features (rendering, Discord presence, asset downloading)
  • FrameworkServer - Server-specific features (HTTP endpoints, command processing, masterlist)
• code/projects/ - Multiplayer projects (auto-discovered, create IGNORE file to exclude)
• code/tests/ - Framework tests
• vendors/ - Third-party dependencies that are not on vcpkg: MafiaNet, CEF, libnode, v8pp, FTL, steamworks, discord, and a handful of small hand-rolled libs. Four are kept here on purpose despite having ports - physfs (the port builds every archiver), tracy (no TRACY_DELAYED_INIT), imguizmo (port predates the ImGui 1.92 AddPolyline change) and miniaudio (port ships only the header). Each carries the reason in vendors/CMakeLists.txt. CEF is downloaded and unpacked into vendors/cef at configure time; set FW_CEF_CACHE_DIR (-D or an environment variable) to share one copy between checkouts and worktrees.
• vcpkg.json - everything else, pinned by builtin-baseline. vcpkg is fetched and bootstrapped at configure time by cmake/VcpkgBootstrap.cmake; override with -DFW_VCPKG_ROOT=<path> (not the VCPKG_ROOT env var, which vcvars64.bat hijacks). Triplets in cmake/vcpkg-triplets/ pin the /MD runtime with static libs, release-only.

Architecture

Core Systems

1. CoreModules (core_modules.h) - Central singleton registry coupling all modules together
2. Replication (networking/replication/) - Native MafiaNet entity replication (ReplicaManager3 + RPC4) with an interest grid for streaming
3. Networking (networking/network_peer.h) - Client-server communication via MafiaNet
4. Scripting (scripting/) - JavaScript/TypeScript scripting for game logic (Server: libnode, Client: V8)
5. GUI Manager (gui/manager.h) - UI using CEF and Dear ImGui
6. Job System (jobs/job_system.h) - Opt-in fiber-based task scheduling using FTL
7. Voice (voice/) - Proximity voice chat; the server relays opaque Opus frames (RakVoice) without decoding, routed by VoiceRouter

Integration Layer

The framework provides ready-to-use server and client implementations:

• Server (integrations/server/instance.h) - Complete game server with HTTP endpoints, command processing, scripting, and MafiaHub Services integration
• Client (integrations/client/instance.h) - Game client with rendering, Discord presence, asset downloading, and networking

Both expose virtual methods (PostInit, PostUpdate, PreShutdown, ModuleRegister) for game-specific customization.

Key Patterns

• RPC System: Use FW_SEND_COMPONENT_RPC(rpc, ...) and FW_SEND_COMPONENT_RPC_TO(rpc, guid, ...) for network communication
• Module Registration: Access systems via Framework::CoreModules::Get*() static methods
• Entity Factories: Use PlayerFactory and StreamingFactory for entity creation

Code Style

• Uses .clang-format (LLVM-based) - run scripts/format_codebase.sh to format
• Namespaces: Use namespace Framework::SubModule { with closing comment } // namespace Framework::SubModule
• Header guards: Use #pragma once
• Variables: _ prefix for private members, camelCase naming
• Classes: PascalCase, mark as final when possible

Commit Format

Format: Module: Brief commit description

• Wrap messages at 72 characters
• Rebase on develop branch
• Split changes into atomic commits

Version Semantics

• PATCH: Changes not affecting peer sync or scripting layer
• MINOR: Scripting layer changes
• MAJOR: Netcode, shared ECS modules, or sync flow changes (requires both client and server update)

Key Dependencies

• FTL - Fiber Tasking Library for job system (v2.1.0)
• libnode/V8 - JavaScript scripting (Server uses libnode for full Node.js APIs, Client uses V8 for sandboxed execution)
• MafiaNet - Networking (MafiaHub's fork of RakNet/SLikeNet)
• CEF - Web-based UI (Chromium Embedded Framework)
• Dear ImGui - Immediate mode GUI
• Tracy - Frame profiler (wrapped by utils/profiler.h FW_PROFILE_* macros; toggle with FW_PROFILING)
• spdlog - Logging
• nlohmann/json - JSON parsing