Imported from lobteck3gaming-cmyk/TheFoundry (AGENTS.md). Install upstream with npx skills add lobteck3gaming-cmyk/TheFoundry. Copyright stays with the author.

DarkRP2 Agent Guidelines

This project is the new clean base for FoundryRP. It starts from the DarkRP2 fork of the official Facepunch Sandbox gamemode, and should stay close to the engine and base gamemode patterns unless there is a clear gameplay reason to extend them.

Project Goal

Build a clean, modular DarkRP-style game for S&Box with the useful systems from the old FoundryRP repo moved over carefully. The old FoundryRP repo is a reference and salvage source, not a codebase to copy wholesale.

FoundryRP is the project name, not a machinery or factory theme requirement. The game should feel like a normal modern roleplay game: simple, readable, social, and practical.

Core Principles

• Build systems that are modular, clean, and easy to extend.
• Write readable, simple, and maintainable code.
• Reuse existing Sandbox and DarkRP2 features whenever possible.
• Never trust the client. Host/server authority owns gameplay truth.
• Prefer small components with clear responsibilities over large manager files.
• Keep player movement, collision, body setup, clothing, and spawn flow as close to the clean DarkRP/engine path as possible.
• Do not reintroduce old FoundryRP complexity unless the migration guide explicitly allows it.

Foundry Migration Rule

When importing from D:\Serv\safe\FoundryRP, migrate behavior, assets, and useful content only after mapping them to DarkRP's existing systems.

Do not copy a Foundry subsystem just because it exists. First ask:

• Does DarkRP already have an owner system for this?
• Can the feature be expressed as a small extension of that system?
• Does the old Foundry code depend on RPG snapshots, custom spawn flow, soft collision patches, or SWB?
• Can the feature be tested in isolation before the next migration slice?

If the answer is unclear, stop and document the intended owner files before editing.

Systems To Preserve From DarkRP

These are the clean base and should not be replaced during migration:

• Code/Player/Player.cs and its existing partials for spawn, control, death, jobs, law, doors, shops, inventory, and persistence.
• Code/GameLoop/GameManager.cs for scene startup and player spawn flow.
• Code/Jobs/JobDefinition.cs, JobManager.cs, and JobVoteManager.cs.
• Code/Game/Law/CityLawManager.cs and the existing mayor/lawboard flow.
• Code/Player/PlayerInventory.cs, PlayerLoadout.cs, and the BaseCarryable / BaseWeapon stack.
• Code/Map pressable/button/door patterns.
• Existing Dresser-based job clothing and avatar appearance handling.
• Existing IPressable tooltip and interaction flow.
• Existing engine player collision and controller behavior.

Systems Not To Import From Old Foundry

Do not bring these into the DarkRP repo:

• Code/Rpg/*
• RPG slot snapshots, spawn-screen character snapshots, or appearance snapshot authority.
• Old Foundry spawn-screen handoff logic.
• Player soft-collision, overlap stabilizer, or collision debug patch components.
• Custom player movement/collision authority layers.
• Old secondary clothing manager paths that compete with Dresser.
• SWB weapon framework code under _external/swb.
• Any weapon that depends on SWB without first being rewritten for DarkRP's BaseWeapon stack.
• Old experimental debug components unless they are rewritten as temporary, clearly named diagnostics.

Migration Priority

Migrate in this order. Each phase should be usable and tested before the next one starts.

1. Project identity, package settings, launch/test hygiene, and documentation.
2. Mayor/civic features that extend DarkRP's mayor, city law, and economy systems.
3. Selected non-SWB weapons rewritten onto BaseCarryable / BaseWeapon.
4. Elevator and map interactable systems using IPressable and DarkRP map patterns.
5. Vehicle systems after the base two-client player collision and animation smoke test remains clean.
6. Optional later systems such as phone, dispatch, jobs, or heist features, one slice at a time.

Mayor And Civic Direction

DarkRP already has a mayor job, CityLawManager, scoreboard law editing, lawboard item, wanted/arrest logic, and roleplay data. Foundry civic work should extend that base instead of replacing it.

Prefer:

• new mayor terminals as IPressable world components
• host-authoritative city settings and economy mutations
• small [Sync( SyncFlags.FromHost )] state for client-visible civic data
• UI panels that read DarkRP player/job/law data directly

Avoid:

• importing the old Foundry mayor stack unchanged
• duplicating CityLawManager
• creating a second law/job/economy truth source
• adding RPG progression requirements to mayor features

Weapons Direction

DarkRP already has a working weapon stack:

• BaseCarryable
• BaseWeapon
• BaseBulletWeapon
• MeleeWeapon
• weapon model/viewmodel/worldmodel helpers
• weapon shop and shipment catalogs
• inventory slots and job-locked loadout items

When importing Foundry weapons:

• skip SWB entirely
• port one weapon at a time
• keep the DarkRP inventory and drop paths
• use real packaged prefabs, viewmodels, worldmodels, sounds, and icons
• register shop/shipment entries through existing DarkRP catalogs
• validate owner input through host RPCs when gameplay state changes

Vehicle Direction

Vehicles are high risk because they touch physics, seats, cameras, player input, ownership, HUD, and collision-adjacent behavior.

Do not migrate vehicles until:

• base DarkRP player movement is unchanged
• a two-client collision/animation smoke test passes
• mayor/civic and selected weapons are stable

When vehicles begin, start with the smallest slice:

• one simple vehicle prefab
• one driver seat
• enter/exit interaction
• host-owned vehicle body at rest
• no cargo, dealer, garage, police extras, or job leasing in the first pass

Only add dealer, garage, cargo, lights, sirens, taxi, and job-issued vehicles after the basic seat/drive/exit loop is stable.

Elevator And Map Interactable Direction

Elevators and map interactables should follow DarkRP's Code/Map style.

Prefer:

• Component.IPressable
• explicit tooltips
• host-owned movement/state
• small components attached to scene or prefab objects
• map-local configuration through properties

Avoid:

• global manager code for one elevator
• custom input stacks
• player movement overrides
• client-owned moving platforms unless the engine pattern requires it

Networking Rules

• Economy, jobs, mayor actions, law changes, purchases, arrests, vehicle spawning, and world mutations are host-authoritative.
• Owner-side prediction is allowed only for feel, never as final gameplay truth.
• Use [Sync( SyncFlags.FromHost )] for host-written state on owner-owned or client-visible objects.
• Validate RPCs by caller, range, role/job permission, target validity, and rough aim where needed.
• Do not require exact host/client trace parity for legitimate remote-client actions.
• Do not trust a client-passed GameObject without host-side validation.
• Build important prefab hierarchy before NetworkSpawn().
• Use Network.Refresh() after host-side hierarchy or important component changes.

UI And Asset Rules

• Keep UI simple and consistent with DarkRP's existing UI structure.
• Use a simple modern roleplay look. Avoid forcing an industrial, machinery, factory, or heavy foundry visual theme just because of the project name.
• Favor clear layouts, readable typography, restrained color, and fast scanning over decorative chrome.
• Use existing HUD roots, scoreboard/shop patterns, notices, and PressableHud when possible.
• Shippable UI textures should resolve through ui/....
• Source UI art should live under Assets/ui/....
• Do not rely on local-only generated textures for gameplay UI.
• Published/package-backed multiplayer testing is the truth for remote-client asset visibility.

Validation Gates

Before calling a migrated slice done:

• Build or compile the project if possible.
• Run a local solo smoke test.
• Run a two-client smoke test for player movement, collision, animation, inventory switching, and the migrated feature.
• If assets, UI icons, prefabs, sounds, or client-visible content changed, test against a published/package-backed server.
• Keep temporary diagnostics clearly named and remove them after the issue is understood.

For every migration phase, keep a short note in Code/Docs/FOUNDRY_MIGRATION_GUIDE.md or a more specific docs file if one exists.

Folder Ownership

Prefer extending existing DarkRP owner folders:

• player/job/law changes: Code/Player, Code/Jobs, Code/Game/Law
• weapons: Code/Weapons, Code/Game/Weapon, Code/Economy/Weapons
• map interactables/elevators: Code/Map
• items: Code/Items
• UI: Code/UI

Create Code/Foundry/* only when a feature has no natural DarkRP owner yet. If a Code/Foundry/* feature becomes core DarkRP behavior, move it into the owning DarkRP folder instead of leaving a permanent parallel architecture.

Coding Style

• Favor explicit behavior over clever abstractions.
• Keep files focused and readable.
• Avoid unnecessary prefixes, duplicates, or inconsistent casing.
• Use structured APIs and existing helpers instead of ad hoc string parsing.
• Add comments only where they explain non-obvious behavior.
• Do not make broad refactors while migrating a feature slice.