Source Code Structure (C++)

Canonical GDD content

This defines how the C++ source is organized so it mirrors the design and stays maintainable. It complements the content layout in 03-Content-Folder-Structure.md.

Current state (from disk)

Source/
  Lambeer.Target.cs
  LambeerEditor.Target.cs
  Lambeer/
    Lambeer.Build.cs
    Lambeer.cpp / Lambeer.h
    LambeerCharacter.{h,cpp}
    LambeerGameMode.{h,cpp}
    LambeerPlayerController.{h,cpp}
    Variant_Combat/        # template example — TO BE REMOVED
    Variant_Platforming/   # template example — TO BE REMOVED
    Variant_SideScrolling/ # template example — TO BE REMOVED

The three Variant_* folders are Third Person template demos and will be deleted (see 05-Project-Setup-Steps.md). The base LambeerCharacter/GameMode/PlayerController are kept and evolved.

Target structure — [RECOMMENDATION]

Organize the runtime module by feature. Start with one runtime module (Lambeer) using folders; split into multiple modules only if build times or boundaries demand it later.

Source/
  Lambeer.Target.cs            # client/standalone target
  LambeerEditor.Target.cs      # editor target
  LambeerServer.Target.cs      # dedicated server target (ADD — Linux)  [RECOMMENDATION]
  Lambeer/
    Lambeer.Build.cs
    Lambeer.{h,cpp}            # module impl
    Core/                      # framework: GameMode, GameState, PC, PS, GameInstance, subsystems
    Character/                 # ALambeerCharacter + base pawn logic
    Components/                # shared character components (or co-locate per feature)
    Combat/                    # weapons, damage, projectiles, recoil
    Survival/                  # USurvivalStatsComponent, status effects, wetness/rain exposure
    Inventory/                 # inventory, equipment, item structs
    Building/                  # build component, building piece actors/records
    Crafting/                  # crafting component, recipe resolution
    Interaction/               # interaction component + interactable interface
    AI/                        # zombie pawns, AI controllers, StateTree tasks, EQS
    Items/                     # item data assets + base types
    Vehicles/                  # vehicle pawn(s) (Phase 2)
    Persistence/               # save/load abstraction + subsystem
    Social/                    # squads, clans, group registry
    UI/                        # C++ side of UI (HUD class, widget base classes)
    Data/                      # USTRUCT/UENUM shared data type definitions
    Lambeer.h forwarders, etc.

Within each feature folder, keep headers and sources together (the template style) or split Public//Private/ — pick one and be consistent. The template uses flat folders, which is fine for a single module.

Module / target notes

• LambeerServer.Target.cs — add a dedicated-server target so the Linux server build is first-class from Phase 1. Critical because the entire game is server-authoritative (see ../04-Multiplayer/01-Network-Architecture.md).
• Lambeer.Build.cs — declare module dependencies explicitly (e.g., EnhancedInput, StateTreeModule/GameplayStateTreeModule, AIModule, UMG, NetCore, GameplayAbilities if GAS is adopted, ChaosVehicles in Phase 2). Add as features land; don't pre-add unused deps.
• Editor-only code (tools, custom editor utilities) must be guarded/WITH_EDITOR or live in an editor module if it grows.

Dependency direction

• Core and Data are low-level; feature modules depend on them, not vice-versa.
• Features communicate via interfaces (UINTERFACE) and components, not hard cross-feature includes, to keep the graph acyclic.
• Persistence depends on feature data structs (to save them) but features should depend on a persistence interface, not the backend.

When to split into multiple modules — [RECOMMENDATION]

Defer until justified. Split when: build/iteration times hurt, or you need a clean editor/runtime boundary, or you want a reusable plugin. Candidate first split: an Editor module for custom tooling; later a LambeerAI or LambeerCore if the single module grows large.