Technical Primer: Navigating the Architecture of Public Nuisance City

Technical Primer: Navigating the Architecture of Public Nuisance City

1. The Big Picture: A Multi-Platform RPG Ecosystem

The Public Nuisance City project (internally known as the COSINE project) is a high-fidelity simulation designed to model the intersection of health equity and systemic bias. Far from being a monolithic program, this ecosystem is a modular collection of technologies working in concert to manage 100 procedurally generated zones. These zones are categorized into functional urban sectors: Medical (ER, ICU), Support (Logistics, Maintenance), Admin (Security, IT), and Patient (Triage, Isolation) areas.

Core Concept The COSINE project is a multi-engine TTRPG (Tabletop Role-Playing Game) simulation. It utilizes procedural generation and live data synchronization to challenge players to navigate medical emergencies and social friction within a simulated urban environment.

Once the "what" of the city is understood, we must look at the "how." Every movement a player makes and every social friction encountered is governed by a central software "brain" designed for complex, non-deterministic logic.

--------------------------------------------------------------------------------

2. The Logic Engine: Why Python Powers the "Brain"

To handle the "Social Logic" and "Bot Interaction" that drive the city, the stack utilizes Python 3.10+. As an architect, I chose Python for its ability to handle asynchronous events via the discord.py library. In a live simulation, social friction and equity audits are not always linear; Python allows the system to react to multiple player inputs simultaneously without breaking the simulation’s state.

This "Brain" is specifically tasked with managing the PADOOS system (the inherent, biased computational framework of the city). Players use specialized scripts to bypass PADOOS biases during "Humanity Audits."

Python Component

Role in the City

bot.py

The Main DOVIC Engine; manages slash commands and button interactions within Discord.

humanity_audit.py

A specialized logic script allowing players to bypass the PADOOS system’s inherent biases.

tug_of_war.py

Tracks the "Equity vs. Efficiency" poles, calculating how player choices shift the city's balance.

The "So What?": Python is the ideal choice here because it handles the non-deterministic aspects of the simulation. Whether it is an EmergencyProtocolTimer.py or a humanity audit, Python processes the "gray areas" of social simulation—where rules are influenced by player behavior rather than just rigid code—and then pushes that state to the rest of the stack.

Once the Python logic engine determines the state of the city and its social balance, that data must be rendered—this is where the JavaScript visual layer takes over.

--------------------------------------------------------------------------------

3. The Visual Engine: JavaScript and the 2D/3D World

The visual experience of Public Nuisance City is powered by JavaScript, utilizing a modular "Engine Switcher" (main.js) to transition between different viewing modes. This allows the simulation to scale its visual fidelity based on the player's current task.

  • Phaser 3 (2D Engine): Contained in engine-2d.js, this library handles the Map View. It is optimized for "City Navigation," allowing players to move through the 100 zones with minimal overhead.
  • Three.js (3D Engine): Contained in engine-3d.js, this library handles the Bay View. When a player enters a specific medical bay, the system switches to this 3D engine to provide high-detail interactions with clinical equipment.

This dual-engine approach ensures the project is performant on platforms like Replit while remaining visually immersive. These disparate visual and logic components are held together in one organized repository.

--------------------------------------------------------------------------------

4. The Central Hub: GitHub as the Project's "Single Source of Truth"

GitHub serves as the "Single Source of Truth" for the COSINE project, acting as the bridge between local development and deployment platforms like Replit or the Unity QOL Environment.

📂 GitHub Repository Structure

/
├── .github/workflows/   # Automated deployment pipelines
├── assets/              # 2D Sprites, 3D Models, and Textures
├── src/                 # The Core Visual Engine
│   ├── main.js          # The Engine Switcher
│   ├── engine-2d.js     # Phaser 3 (Map View)
│   ├── engine-3d.js     # Three.js (Bay View)
│   └── firebase-app.js  # The JavaScript/Firebase Bridge
├── backend/             # GAS & Firebase logic
│   ├── Code.gs          # Google Apps Script (The Pipeline to Firebase)
│   └── appscript.json   # GAS Manifest and Scopes
├── index.html           # Main Entry Point
├── README.md            # Project Documentation & Zone Registry
└── .gitignore           # Crucial Security Filter

In this architecture, the backend/ folder is vital: it contains the Google Apps Script (GAS) logic (Code.gs) that acts as the pipeline between the Firebase Realtime Database and the frontend engines. Furthermore, the .gitignore file is the project's first line of defense; it ensures that environment secrets, such as serviceAccountKey.json and Firebase API keys, are never leaked to the public.

--------------------------------------------------------------------------------

5. Data Landscapes: Hazards, Threats, and Difficulty Scaling

The city's difficulty is not static; it scales alongside the narrative progression of the "DOVIC Outbreak." By analyzing the JSON logs, we can see how the environment becomes increasingly hostile as the server version advances.

Environmental Dangers

We distinguish between Atmospheric Hazards (general environmental conditions) and Facility Threats (specific system failures or risks).

Atmospheric Hazards

Facility Threats

Darkness / Low Oxygen

Biohazard Leak / Security Breach

Fog / Rain

Radiation Warning / Hostile Entity

Static Discharge / Smoke

Sparking Wires / Power Fluctuation

Chemical Smell / Steam Leak

Equipment Failure / Structural Damage

The "Resource Squeeze": Multipliers and ARP Credits

The simulation uses an Adaptive Token Credit system to force players into difficult ethical choices. As the outbreak progresses, the difficulty_multiplier increases, creating a "resource squeeze" where arp_credits (Adaptive Resource Points) become significantly more scarce.

  • Initial Deployment (v1.0.0): Multiplier is 1.1 with 4,955 credits available.
  • Phase 1 (v1.0.4): The multiplier rises to 1.7.
  • Phase 2 (v1.1.1): The multiplier reaches 2.0.
  • Phase 3 (v1.2.1): The multiplier hits 2.3.
  • Facility-Wide Lockdown (v1.3.0): The multiplier peaks at 2.4, with credits slashed to just 1,899.

This data-driven scaling forces the "Equity vs. Efficiency" theme: as resources vanish and threats like "Sparking Wires" or "Biohazard Leaks" increase, players must decide if they will save everyone (Equity) or simply survive (Efficiency).

--------------------------------------------------------------------------------

6. Summary Checklist for New Learners

To begin contributing to the COSINE project, follow these sequence steps:

  1. Initialize Backend: Create a Firebase Project and download your serviceAccountKey.json.
  2. Clone & Configure: Clone the COSINE-Game-Server repository and create a .env file for your Discord Token and Firebase paths (ensure these are in your .gitignore).
  3. Sync and Deploy: Use git add, commit, and push to update the Single Source of Truth. You can then import the repository directly into Replit for live testing.

Technical Stack Summary

  • State Control: Custom JavaScript Switcher (main.js).
  • Visual Engines: Phaser 3 (City Navigation) and Three.js (Detail Interaction).
  • Backend & Data: Google Apps Script (GAS) + Firebase Realtime Database.
  • Logic: Python 3.10+ (Social Simulation and Discord via discord.py).
  • Environment: 100 procedurally generated zones (Medical, Support, Admin, Patient).
  • Deployment: GitHub to Replit / Unity QOL Environment.

Comments

Post a Comment

Popular Posts