# Galactic Conquest Classic — Project Overview > **For AI assistants and new contributors:** Read this document first before working on any part of the codebase. It describes what the project is, how it is structured, and the conventions you must follow when reading or editing code. --- ## What This Project Is **Galactic Conquest Classic (GCC)** is a browser-based, multiplayer, persistent-universe strategy game played entirely through text/HTML. It is an MMORPG in the sense that all players share one live universe per server. Players build galactic empires — colonizing planets, researching technology, constructing fleets, forming federations (alliances), trading on a market, and fighting other players or NPC factions. - **Developer/Owner:** Wolfren Industries - **Current Version:** 2.77 (this is the 2.0 rewrite of the original GC) - **Repo Purpose:** This is the **active development branch**. A separate production deployment exists. Do not assume this repo is identical to what is live. --- ## Game Mechanics Overview ### Turns The central resource in the game is **turns**. Turns are the equivalent of action points or energy in other games — players spend turns to do almost everything: research, build ships, attack, explore, generate income, etc. Turns are **generated automatically by a server-side scheduled process** at a fixed rate for all players simultaneously: | Server | Turn Rate | Notes | |------------|--------------------|------------------------------| | Real-Time | 1 turn / 8 seconds | Most popular server | | Turn-Based | 1 turn / 2.5 min | Consolidated from legacy x4 | Turns accumulate up to a cap. The scheduled processes that grant turns live in the `Z_*.cfm` background process files. ### Universe Both servers run **persistent universes** — there are no resets or seasons. The game world is ongoing. ### Servers The application was originally designed to support up to **5 servers** (`this.ServerMax = 5` in `Application.cfc`). Today only two exist: **Real-Time** and **Turn-Based**. Legacy code throughout the codebase may reference server slots 3–5; these are currently inactive and can be treated as dead code unless explicitly stated otherwise. --- ## Architecture | Layer | Technology | |--------------|-------------------------------------------------| | Language | ColdFusion (CF5-compatible syntax, Lucee engine)| | Web Server | Apache 2 on Debian 12 | | Database | MySQL 8 — primary schema: `gcc` | | Frontend | Server-rendered HTML + jQuery-era JavaScript | | Styles | Plain CSS (59 files) | ### ColdFusion / Lucee Notes - The codebase targets **CF5-compatible syntax** running on the **Lucee CFML engine**. - Components use `.cfc` files; templates use `.cfm` files. - Custom tags are used extensively: `` calls map to `.cfm` files acting as reusable components. - Application-scope variables are used for caching frequently needed data (avoid unnecessary re-queries). ### Database Only the **`gcc`** database schema is relevant to gameplay. Additional datasources (`ucc`, `ucc_log`, `gcs`, `gcs_log`, `gcc_log`) are defined in `Application.cfc` due to legacy requirements but are not actively used for core game logic. When working on game features, focus exclusively on `gcc`. All datasource credentials and connection strings are in `Application.cfc`. ### Frontend The UI is **fully server-rendered** — every page is assembled by ColdFusion and delivered as HTML. JavaScript is used for progressive enhancement only (table sorting via TableSorter, AJAX calls for specific interactions, UI helpers). There is no SPA framework. When editing UI, edit the `.cfm` template files. --- ## Repository Structure ``` GCC-Dev/ ├── Application.cfc # App config: datasources, session/client settings, server slots ├── i.cfm # Main router — all requests route through here via url.f / url.p │ ├── p_*.cfm # Page templates (public-facing rendered pages) ├── f_*.cfm # Feature files (game actions: attacks, market, research, etc.) ├── s_*.cfm # System/utility files (shared logic, loaders, helpers) ├── i_*.cfm # Include/partial templates (headers, footers, reused UI fragments) ├── Z_*.cfm # Background/scheduled processes (turn generation, upkeep, DB updates) │ ├── Modules/ │ ├── Controllers/ # CFC-based controllers for modular features │ │ ├── Projects/ # Project system controllers │ │ └── HT/Projects/ # High-tech project variants │ ├── Pages/ # View templates for modular features │ │ └── Projects/ │ ├── Functions/ # Shared utility functions (Functions.cfm, etc.) │ ├── NPC/ # NPC and fleet generation logic │ │ └── Fleet/ │ └── Ships/ # Ship builder logic │ ├── edmin/ # Admin panel (168+ files) — user mgmt, moderation, stats, effects ├── forum/ # Forum system v1 ├── forum2/ # Forum system v2 ├── help/ # In-game help documentation (HTML) ├── text/ # In-game manual pages (manual_*.cfm) ├── Stats/ # Statistics and reporting ├── JS/ # JavaScript files (84 files) ├── CSS/ # Stylesheets (59 files) ├── i/ # Image assets └── l/ # Localized content ``` --- ## File Naming Conventions | Prefix | Type | Example | |-----------|-----------------------|----------------------------------| | `p_` | Public page template | `p_login.cfm`, `p_signup.cfm` — unauthenticated only | | `f_` | Feature / game action | `f_com_attack.cfm`, `f_fed.cfm` | | `s_` | System / utility | `s_endturn.cfm`, `s_loadsystem.cfm` | | `i_` | Include / partial | `i_header.cfm`, `i_nav.cfm` | | `Z_` | Background process | `Z_Hourly_Processes.cfm` | | `f_com_` | In-game command file | `f_com_ship.cfm`, `f_com_research.cfm` | | `f_admin_`| Admin panel action | `f_admin_user.cfm` | | `f_fed_` | Federation feature | `f_fed_members.cfm` | --- ## Request Routing All web requests flow through **`i.cfm`** (the main entry point). There are two distinct routing paths: **Authenticated (in-game) requests** — `url.f` is present and `session.userid` is set: - `url.f` specifies the feature/action file to execute (e.g., `i.cfm?f=com_attack`) - The page frame (nav, layout) is provided by `i_*.cfm` layout wrappers (e.g., `i_f_800.cfm`) - `p_*.cfm` files are **not** involved here **Public (unauthenticated) requests** — no `url.f`, or `session.userid` is absent: - Falls through to `i_p.cfm`, which reads `url.p` to determine which `p_*.cfm` to render - `p_*.cfm` files are exclusively for the public-facing side: login, signup, landing pages, etc. - `url.p` is only meaningful in this public context The system loads shared application state via `s_loadsystem.cfm` early in the request lifecycle. --- ## Major Feature Areas | Area | Key Files / Locations | |-------------------|--------------------------------------------------------| | Authentication | `p_login.cfm`, `p_signup.cfm` | | Turn system | `s_endturn.cfm`, `z_endturn.cfm`, `Z_Hourly_Processes.cfm` | | Colony management | `f_com_col*.cfm` | | Ship building | `f_com_ship*.cfm`, `Modules/Ships/Builder.cfm` | | Research | `f_com_research*.cfm` | | Exploration | `f_com_explore*.cfm` | | Combat / Attacks | `f_com_attack*.cfm`, `s_com_attack*.cfm` | | Federations | `f_fed*.cfm` | | Market / Economy | `f_com_market*.cfm` | | Projects | `Modules/Controllers/Projects/`, `Modules/Pages/Projects/` | | NPC system | `Modules/NPC/` | | Private messages | `f_pm.cfm` | | Sector messages | `f_com_msgsector*.cfm` | | Forums | `forum/`, `forum2/` | | Donations / Store | `f_com_donate*.cfm`, `f_com_cart*.cfm` | | Background jobs | `Z_*.cfm`, `Z_Upkeep_Calc.cfm`, `Z_UpdateDB*.cfm` | | Admin panel | `edmin/` | | Statistics | `Stats/` | --- ## Security Patterns Be aware of the following when reading or modifying code: - **`ihasrunflag`** — A guard variable set at the top of many files to prevent direct URL access. Any `.cfm` that should only be called as an include (not navigated to directly) checks this flag. - **SQL injection protection** — URL and form inputs are sanitized via `Modules/Functions/Functions.cfm`. Do not write raw `url.*` or `form.*` values directly into queries. - **Session validation** — Session state (including IP tracking) is checked on protected pages. Admin access is gated by an admin flag on the user record. - **Hack detection** — Unusual inputs or state are caught in `Functions.cfm` and logged. --- ## Key Configuration File **`Application.cfc`** is the single most important configuration file. It controls: - Application name, version, and server slot count - All database datasource definitions - Session and client management settings - PayPal integration flags (sandbox vs. production) - Development/production mode switches Read this file first when diagnosing environment or connection issues. --- ## Background Processes Scheduled tasks run independently of web requests and handle time-sensitive game logic: | File | Purpose | |-----------------------------|----------------------------------------------| | `Z_Hourly_Processes.cfm` | Master hourly job dispatcher | | `z_endturn.cfm` | Turn generation for all players | | `Z_Upkeep_Calc.cfm` | Ship upkeep cost calculation | | `Z_UpdateDB*.cfm` | Database maintenance and data migrations | These are triggered by a server-side scheduler (not by user requests). When debugging turn-related issues, start here. --- ## Known Legacy / Technical Debt - **5-server references:** `this.ServerMax = 5` and related logic — only slots 1 (Real-Time) and 2 (Turn-Based) are active. References to servers 3–5 are inert. - **Extra datasources:** `ucc`, `ucc_log`, `gcs`, `gcs_log` are defined but not used for core game logic. They exist to avoid connection errors from legacy code. - **Two forum systems:** `forum/` and `forum2/` both exist. Treat `forum2/` as the current one unless working directly in the forum subsystem. - **`_ids.txt` files in `edmin/`:** Plain-text ID-to-name mappings for projects and research items. Useful reference when working with those systems. --- ## How to Navigate This Codebase (for AI Assistants) 1. **Start with `Application.cfc`** to understand the environment and database setup. 2. **Trace requests through `i.cfm`** — identify `url.f` and `url.p` to find the relevant feature and page files. 3. **Use file prefixes as a map** — `f_com_*` for player actions, `s_*` for shared utilities, `Z_*` for scheduled jobs. 4. **Check `Modules/Functions/Functions.cfm`** for shared helper functions before assuming logic doesn't exist. 5. **The `gcc` database is the only one that matters** for game features. Ignore other datasources unless explicitly instructed. 6. **Do not break the `ihasrunflag` pattern** — if adding a new include file, include this guard. 7. **More documentation will be added** — this is a high-level overview. Feature-specific docs will be created separately.