t2-mapper/CLAUDE.md

• Keep track of what your current working directory is, and consider it when running shell commands. Running a command in a directory you didn't expect can potentially be catastrophic. Always use the correct relative paths to files based on the current directory you are in.
• Some scripts may expect the current working directory of the process to be a specific path. For example, most scripts in the scripts folder expect to be run from the root of the repository, so file and directory paths are relative to that.
• Always write new scripts in TypeScript. 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 are importing it instead (like importing the default export, import * as ..., or other strategies).
• Despite preferring TypeScript, it's OK if some code generation tools output .js, .cjs, or .mjs files. For example, Peggy (formerly PEG.js) generated parsers are JavaScript. Likewise with .js files that were generated by the TorqueScript transpiler.
• TypeScript can be executed using tsx.
• Don't commit to git (or change any git history) unless requested. I will review your changes and decide when (and whether) to commit.
• Import Node 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 a lot of exports with short names. It often looks nicer to refer to them in code like fs.readFile, path.join, and so on.
• Format code according to my Prettier settings. If there is no Prettier config defined, use Prettier's default settings. After any code additions or changes, running Prettier on the code should not produce any changes. Instead of memorizing how to format code correctly, you may run Prettier itself as a tool to do formatting for you.
• The TorqueScript grammar written in Peggy (formerly PEG.js) can be rebuilt by running npm run build:parser.
• Typechecking can be done with npm run typecheck.
• Game files and .vl2 contents (like .mis, .cs, shapes like .dif and .dts, textures like .png and .ifl, and more) can all be found in the docs/base folder relative to the repository root.
• You are most likely running on a macOS system, therefore some command line tools (like awk and others) may NOT be POSIX compliant. Before executing any commands for the first time, determine what type of system you are on and what type of shell you are executing within. This will prevent failures due to incorrect shell syntax, arguments, or other assumptions.
• Do not write excessive comments, and prefer being concise when writing JSDoc style comments. Assume your code will be read by a competent programmer and don't over-explain. Prefer excluding @param and @returns from JSDoc comments, as TypeScript type annotations and parameter names are often sufficient - let the function names, class names, argument/parameter names, and types do much of the talking. Prefer only writing the description and occasional @example blocks in JSDoc comments (and only include examples if the usage is somewhat complex).
• JSDoc comments are more likely to be needed as documentation for the public API of the codebase. This is useful for people reading docs (which may be extracted from the JSDoc comments) or importing the code (if their IDE shows the JSDoc description). You should therefore prioritize writing JSDoc comments for exports (as opposed to internal helpers).
• When in doubt, use the already existing code to gauge the number of comments to write and their level of detail.
• As for single-line and inline comments, only write them around code if it's tricky and non-obvious, to clarify the motivation for doing something.
• Don't write long Markdown (.md) files documenting your plans unless requested. It is much better to have documentation of the system in its final state rather than every detail of your planning.
• Do not make any assumptions about how TorqueScript works, as it has some uncommon syntax and semantics. Instead, reference documentation on the web, or the code for the Torque3D SDK, which contains the official grammar and source code.