Architecture

Novactorio is deliberately framework-free on the rendering side. The game loop, simulation, and drawing are hand-written on the Canvas 2D API; React is used only for UI overlays. The codebase spans 21,000+ lines of TypeScript (21,257 LOC across src/).

Layer overview

┌─────────────────────────────────────────────────────────┐
│  React overlay (src/components/, src/ui/)               │
│  Auth → Start → Game routing, HUD, menus, chat, shop    │
└─────────────────────────┬───────────────────────────────┘
                          │ game state / events
┌─────────────────────────▼───────────────────────────────┐
│  Game engine (src/game/)                                │
│  engine.ts   — main loop: update() + render(), entities │
│  systems.ts  — supply chains, belts, pipes, AI, pollution│
│  world.ts    — chunk storage, infinite scrolling        │
│  noise.ts    — Perlin noise terrain generation          │
│  renderer.ts — 10 dedicated draw methods                │
│  constants.ts, types.ts, audio.ts, postproc.ts          │
└─────────────────────────┬───────────────────────────────┘
                          │
┌─────────────────────────▼───────────────────────────────┐
│  Render pipeline (src/render/)                          │
│  AmbientAtmosphere · ParticleEffects · PollutionOverlay │
│  ScreenEffects · SpriteManager · WeatherSystem · utils  │
└─────────────────────────────────────────────────────────┘

Source map (src/)

Directory	Files	Responsibility
game/	9	Engine core: loop, systems, world, noise, renderer, audio, postprocessing
core/	engine, systems, types	Shared engine/system/type definitions
render/	7	Visual effects: atmosphere, particles, pollution, weather, sprites, screen FX
components/	—	React UI: AuthScreen, BuildMenu, ChatPanel, shop, HUD
services/	auth, coop, trade	Supabase-backed services
config/	—	Environment-driven configuration
ui/	—	Additional UI primitives
easter/	—	Easter-egg content
shaders/	—	Shader definitions
lib/	—	Shared utilities

Game engine (src/game/)

Module	Responsibility
engine.ts	Game loop (update/render), entity lifecycle, building logic, inventory, combat, particles
renderer.ts	Extracted render passes: sky, ground, entities, damage numbers, etc.
systems.ts	Supply chains, conveyor belts, pipe networks, enemy AI, pollution
world.ts	Chunk-based world, block storage, infinite scrolling
noise.ts	Perlin noise for terrain generation
types.ts	Shared type definitions
constants.ts	Tuning constants
audio.ts	Sound effects
postproc.ts	Post-processing effects

Render pipeline (src/render/)

Module	Responsibility
AmbientAtmosphere.ts	Sky/atmosphere rendering
ParticleEffects.ts	Particles (smoke, sparks, damage)
PollutionOverlay.ts	Pollution visualization
ScreenEffects.ts	Screen-space effects
SpriteManager.ts	Sprite atlas management
WeatherSystem.ts	Weather simulation
utils.ts	Render helpers

Services (src/services/)

Service	Responsibility
auth	Supabase authentication integration
coop	Co-op multiplayer via Supabase Realtime
trade	Player trading (Stripe-fee checkout for trades)

Rendering approach

The renderer is organized as discrete draw methods (sky, ground, entities, particles, damage numbers, …) rather than a monolithic draw call, keeping each pass cheap and debuggable. World chunks are culled to the visible area while scrolling. The render pipeline is further split into dedicated modules (atmosphere, particles, pollution, weather) layered over the base canvas.

UI overlay

React 18 renders the interface on top of the canvas: full screen routing (Auth → Start → Game), build menu, chat panel, shop, stats, and settings. State flows from the engine into React through a shared game-state bridge.

TypeScript strictness

tsconfig.app.json runs with strict typing; the project validates with tsc --noEmit (npm run typecheck) and lints with ESLint (npm run lint).

Scripts

Script	Purpose
npm run dev	Vite dev server
npm run build	Production build
npm run typecheck	TypeScript validation
npm run lint	ESLint
npm run preview	Build + local Wrangler preview
npm run deploy	Build + wrangler deploy (Cloudflare)
npm run easter-egg	Easter-egg generator script

Deployment target

The game builds with Vite and deploys to Cloudflare via Wrangler (wrangler.jsonc), with Supabase as the backend.