t2-mapper/CLAUDE.md

Introduction

This project implements Tribes 2 map rendering using Three.js. Since we have access to partial Tribes 2 source code and the open source Torque3D engine, as well as the original game assets, the game's rendering pipeline can be reproduced almost exactly. The primary concept demonstrated in this project is that a Torque mission file (which defines an object tree similar to a scene graph) can be mapped to a React component tree.

Technologies

• Node.js
• npm
• TypeScript
• React
• Next.js
• Three.js
• react-three-fiber (r3f)
• TanStack Query
• Peggy (formerly PEG.js)
• Vitest

Project Structure

• app/ - Next.js application.
• docs/ - Build output from Next.js static export. It's only called "docs" because that's where GitHub Pages will look for it. NOT intended for actual docs. Don't add or look for documentation here!
• docs/base/ - Game files from Tribes 2, including extracted .vl2 contents. Missions/scripts (.mis, .cs), models/shapes (.dif, .dts, and their .glb conversions), textures (.png, .bmp, .ifl), and more. This folder is actually very helpful to explore, especially when debugging specific maps.
• src/ - Core implementation.
• src/components/ - React components and hooks.
• src/torqueScript/ - TorqueScript transpiler and runtime.
• scripts/ - Helper scripts. TypeScript files can be run directly with tsx. Python scripts are intended for use with Blender's headless background script mode, and should not be executed with Python directly.
• generated/ - Generated code, like the Peggy parser.
• reference/ - Reference materials like docs, plans, screenshots, and more.
• reference/TorqueEngineResources/ - A symlink to a "Torque Engine Resources" folder, which may or may not exist for different developers. Developers can use this to point to additional materials that provide context about Tribes 2, Torque, and how it works (like the engine source code, books, user manuals, game files, and conversion utilities). Use this to answer questions about the engine.
• public/ - Static files for the Next.js app.

Three.js

• Keep colorspace conversions in mind so that we're never passing incorrect color values or mixing colors incorrectly. Tribes 2 specifies all colors in sRGB, and thus all color operations assume sRGB. Three.js, on the other hand, expects linear color values in most circumstances. Pay attention to which colorspace different shaders expect (which may differ depending on the type, like standard vs. Lambert vs. custom).

React

• Scenes should render progressively rather than requiring all resources to be ready up-front. For example, we can render the terrain even if other objects in the scene aren't ready. TanStack Query and Suspense boundaries are used to show placeholders and prevent blocking or "waterfalling" where possible.

Tribes 2: Torque Engine / Torque3D / V12

• Tribes 2 uses an early version of the Torque3D engine known as V12. Thus, it is common to refer to Tribes, Torque, and V12 interchangeably. When in doubt, we're interested in Tribes 2's version of the engine specifically.

• This is an old game. Some of its file formats are now obsolete and thus difficult to find tooling for, especially 3D model formats like DIF (interiors) and DTS (shapes).

• The terms "map" and "mission" are used interchangeably.

TorqueScript

• Do not make any assumptions about how TorqueScript works; it has some very uncommon syntax and semantics (like case insensitivity, barewords strings, and more). Refer to official documentation or the actual Torque3D SDK, which contains the official grammar and source code. Check the TorqueEngineResources folder for related materials.

Code Conventions

General Rules

• Write new scripts in TypeScript unless instructed otherwise.
• Keep code well-formatted. This project uses Prettier, but it may not necessarily handle all languages (like shaders/GLSL or TorqueScript). Run Prettier to format code for you.
• Despite preferring TypeScript, it's OK if some code generation tools output JavaScript files. For example, Peggy generates JavaScript parsers. Likewise with .js files generated by the TorqueScript transpiler. Don't attempt to convert or format these unless requested.

Imports and Exports

• Use ES6 import and export, never require() or createRequire().
• If you think you need to use require() to get something working, try changing how you're importing it instead (like importing the default export, import * as …, or other strategies).
• Import Node's built-in modules using the node: prefix.
• Use Promise-based APIs when available. For example, prefer using node:fs/promises over node:fs.
• For node:fs and node:path, prefer importing the whole module rather than individual functions, since they contain many exports and short, generic names. It looks nicer to reference them in code like fs.readFile, path.join, and so on.
• Don't add new npm dependencies without explicit confirmation.

Comments and Documentation

• Don't add excessive code comments. Prefer being concise when writing JSDoc style comments. Don't over-explain; assume your code and comments will be read by a competent programmer.
• Don't remove existing comments unless they're redundant, incorrect, or outdated.
• Exclude @param and @returns from JSDoc comments, instead preferring self-descriptive TypeScript types and parameter names. Let the function names, class names, argument/parameter names, and types do most of the talking. Prefer only writing the description and occasional @example blocks in JSDoc comments. Only include examples if the usage is complex.
• JSDoc comments may be beneficial for documenting the public API of a module, not just for people reading the code. For example, some documentation generator tools extract JSDoc comments, and IDEs often show JSDoc content in popups to assist developers.
• Only write inline/single line comments around code if it's tricky and non-obvious, to clarify the motivation for doing something.
• When in doubt, use existing code to gauge the number of comments to write and their level of detail.
• Don't add long Markdown files documenting your plans unless requested. It's better to have documentation of a system in its final state rather than every detail of your planning.

Shell Commands and Scripts

• TypeScript can be executed directly using tsx.
• Keep track of your current working directory, and consider it when running shell commands. Running a command in the wrong directory can be catastrophic. Always use the correct relative paths to files based on the directory you're in.
• Some scripts may expect the current working directory to be a specific path. For example, most scripts in the scripts folder expect to be run from the repository root, so file and directory paths are relative to that.
• You are most likely running on a macOS system. Therefore, some command line tools (like awk, grep, and others) may NOT be POSIX compliant. Before running commands for the first time, determine what type of system you're on, what versions it has, and what shell you're executing commands in (like bash vs. zsh). This will prevent failures due to incorrect shell syntax, arguments, or other assumptions.
• Don't run the build script to verify whether a change actually worked. Building the project has the potential to be destructive, since it cleans out existing build artifacts. Additionally, it's much slower than simply running typecheck, and it interferes with the dev server.
• Don't run the dev server to verify changes. The dev server is probably already running.
• The TorqueScript grammar written in Peggy can be rebuilt with the build:parser npm script.
• Typechecking can be done with the typecheck npm script or by running tsc directly.
• The scripts/screenshot.ts tool lets you screenshot a specific camera's viewpoint on a specific mission. It's very useful for verifying visual changes, iterating, and debugging rendering. Read the script to learn how to use it.

Git

• Don't commit to git (or change any git history) unless requested. I will review your changes and decide when (and whether) to commit.
• Unless requested, only use non-destructive git commands (e.g. diff, show, log). Commands like checkout and reset could result in data loss!