KotOR.js Directory Structure

This document describes the project layout. Source is TypeScript; the app is built with Webpack and run under Electron. The main entry is main.js, which loads the compiled Electron main process from dist/electron.

---

Root

Path	Purpose
main.js	Node/Electron entry point; requires ./dist/electron (compiled from src/electron).
README.md	Project overview and setup.
package.json	Scripts, dependencies, and main: "dist/KotOR.js" for the bundled library.
tsconfig.json	Base TypeScript config.
tsconfig.electron.json	Electron main process (compiles src/electron → dist/electron).
tsconfig.kotorjs.json	Core KotOR library bundle.
tsconfig.launcher.json	Launcher app.
tsconfig.game.json	Game app.
tsconfig.forge.json	Forge editor app.
tsconfig.debugger.json	Debugger app.
typedoc.json	API docs (Typedoc → wiki).
electron-builder.json	Electron packaging.

---

Top-level directories

├── src/          # All TypeScript source (game engine, apps, tools)
├── dist/         # Build output (Electron, webpack bundles, assets); generated
├── docs/         # Generated API docs (e.g. enums, interfaces, types)
├── coverage/     # Test coverage reports (e.g. lcov); generated
├── images/       # Project images (e.g. screenshots under images/screenshots)
├── projects/     # User/project data (e.g. project-1)
├── scratch/      # Scratch/experimental (e.g. nwscript)
└── wiki/         # Wiki and design docs (e.g. this file)

---

src/ — Source code

Core engine and game systems

Directory	Purpose
actions/	Game action classes (e.g. ActionOpenDoor, ActionDialogObject).
audio/	Audio engine: ADPCM, AudioEmitter, AudioEngine, AudioFile, AudioLoader, EAXPresets, ReverbEngine; Bink audio DCT used by the Bink worker.
combat/	Combat engine.
controls/	Input control classes.
effects/	Game effect classes (e.g. EffectDeath, EffectVisualEffect, EffectAssuredHit).
engine/	THREE.js objects, effects, utilities; includes menu/, minigames/, pathfinding/, rules/, and SaveGame.
events/	Game event objects (e.g. EventApplyEffect, EventDestroyObject).
module/	Module/area/creature and related runtime.
odyssey/	Odyssey model types and logic; controllers/ for Odyssey controllers.
talents/	Talent objects used by KotOR.
three/	Custom THREE.js classes; odyssey/ for Odyssey/THREE integration.

Resource and asset handling

Directory	Purpose
resource/	Resource types and loaders: CExoLocString, BIF, BIK, ERF, GFF, KEY, LIP, LTR, LYT, RIM, SSF, TGA, TLK, TPC, TwoDA, VIS, etc.
loaders/	Asset loader classes (used by engine and Forge).
shaders/	GLSL shaders; chunks/ and pass/ for shared and pass-specific shaders.

Type definitions and interfaces

Directory	Purpose
enums/	TypeScript enums; grouped by domain (e.g. actions/, audio/, chargen/, combat/, controls/, dialog/, effects/, engine/, events/, graphics/ with tga/, tpc/, txi/, gui/, loaders/, minigames/, module/, nwscript/, odyssey/, resource/, server/ with ipc/).
interface/	TypeScript interfaces; grouped by domain (e.g. animation/, area/, combat/, dialog/, engine/ with pathfinding/, graphics/ with tga/, gui/, input/, loaders/, minigames/, module/ with minigame/, nwscript/, odyssey/ with controller/, resource/, talents/, twoDA/, utility/, filesystem/).
types/	TypeScript type definitions.

Scripting and utilities

Directory	Purpose
nwscript/	NWScript runtime; compiler/, decompiler/, events/; NWScript, NWScriptInstance, NWScriptInstruction, defs for K1/K2.
utility/	General utilities; binary/ for BinaryReader/BinaryWriter and related.
managers/	Game and UI managers (e.g. CharGenManager, JournalManager, CursorManager).
gui/	Shared menu and GUI classes; protoitem/ for proto items.

Video and workers

Directory	Purpose
video/	Video decoding: Bink demuxer/decoder (bink-demuxer, binkvideo, binktypes, binkdata, bink-idct), bit readers (BitReaderLE, BitReaderBE), VLC, and uint helpers.
worker/	Web workers (e.g. bink-worker.ts for Bink video/audio decoding off the main thread).

Electron and apps

Directory	Purpose
electron/	Electron main process (Main.ts, WindowManager, etc.); compiles to dist/electron.
apps/	Application UIs (React-based): launcher, game, Forge editor, debugger; shared code in common/.

Apps layout (src/apps/)

• common/ — Shared app code; components/ (e.g. loadingScreen).
• launcher/ — Launcher window; components/, context/, profiles/, styles/ (e.g. promo-items).
• game/ — In-game UI; components/ (e.g. cheat-console, modal, modal-eula, modal-grant-access), context/, states/, styles/.
• forge/ — Resource/module editor: components/ (tabs for GFF, script, image, model, LIP, 2DA, UTC/UTD/UTE/UTI/UTM/UTP/UTS/UTT/UTW, WOK, ERF, etc.), context/, data/, enum/, helpers/, interfaces/, managers/, module-editor/, states/, styles/.
• debugger/ — Debugger UI; components/, context/, helpers/, states/, styles/.

Game-specific code (src/game/)

• kotor/ — KotOR I: gui/, menu/, minigames/.
• tsl/ — The Sith Lords: gui/, menu/, minigames/.

Server and tests

Directory	Purpose
server/	Backend/Electron IPC and shared objects: ipc/ (IPCMessage, IPCMessageParam), object/ (AreaObject, GameObject, Module).
tests/	Unit tests (e.g. Jest); e.g. BinaryReader.test.ts, resource/ for resource tests.

Static assets (src/assets/)

• icons/ — App/icons.
• launcher/ — Launcher fonts and images.
• forge/ — Forge editor fonts and assets.

Entry and re-exports

• KotOR.ts — Main library entry; re-exports engine, loaders, resource types, NWScript, odyssey, combat, controls, managers, etc.
• GameInitializer.ts, GameState.ts, LoadingScreen.ts — Game bootstrap and state.

---

Build and run

• Electron (desktop): npm run electron:compile (or start) compiles src/electron to dist/electron; main.js loads ./dist/electron.
• Webpack: Builds launcher, game, Forge, and debugger into dist/ (e.g. dist/launcher/, dist/game/, dist/forge/, dist/debugger/).
• Tests: npm test runs Jest on ./src/tests.
• Docs: npm run typedoc generates wiki from ./src/KotOR.ts.

This structure reflects the current codebase; dist/, docs/, and coverage/ are generated and not committed as source.