@gustavo10destroyer/gsc-parser

GSC (Game Script) parser for Call of Duty: Black Ops II (T6). Parses GSC/CSC source code into a complete AST suitable for formatters, linters, language servers, and compilers.

Tested against 2,085 real game scripts — 100% parse success rate.

Install

npm install @gustavo10destroyer/gsc-parser

Quick Start

import { parse, print } from "@gustavo10destroyer/gsc-parser";

const source = `
init()
{
    level.var = 42;
    self thread my_func("hello");
}

my_func(msg)
{
    wait 1;
    self endon("death");
    self notify("done", msg);
}
`;

const ast = parse(source, "myfile.gsc");

// Print back to source
const output = print(ast);
console.log(output);

API

parse(source, filename?, headerLoader?)

Parses a GSC source string and returns a Program AST node.

• source string — GSC source code
• filename string (optional) — source filename for error messages
• headerLoader (name: string) => { name: string; data: string } | null (optional) — callback to load .gsh header files

Returns Program — the root AST node containing includes and declarations.

print(program)

Converts a Program AST back to formatted GSC source code.

• program Program — AST root node
• Returns string — formatted GSC source

Parser class

Lower-level parser with full control:

import { Parser } from "@gustavo10destroyer/gsc-parser";

const parser = new Parser("t6", "myfile.gsc", sourceCode);
const ast = parser.parseSource("myfile.gsc", sourceCode);

AST Overview

The AST has 68 node types organized in 4 categories:

• Program (2): Program, Include
• Declarations (6): DeclFunction, DeclConstant, DeclUsingTree, DeclDevBegin, DeclDevEnd, DeclEmpty
• Statements (28): BlockStatement, IfStatement, IfElseStatement, WhileStatement, DoWhileStatement, ForStatement, ForEachStatement, SwitchStatement, CaseStatement, DefaultStatement, ReturnStatement, BreakStatement, ContinueStatement, ExpressionStatement, WaitStatement, WaitTillStatement, WaitTillMatchStatement, WaitFrameStatement, WaitTillFrameEndStatement, EndOnStatement, NotifyStatement, BreakpointStatement, ProfBeginStatement, ProfEndStatement, AssertStatement, AssertExStatement, AssertMsgStatement, EmptyStatement, DevBlock, StatementList, SwitchBody
• Expressions (32): Identifier, IntegerLiteral, FloatLiteral, StringLiteral, IStringLiteral, PathLiteral, TrueLiteral, FalseLiteral, UndefinedLiteral, AnimTreeExpression, AnimationExpression, SelfExpression, GameExpression, AnimExpression, LevelExpression, ThisThreadExpression, EmptyArrayExpression, VectorExpression, ParenExpression, SizeExpression, FieldExpression, ArrayExpression, TupleExpression, ReferenceExpression, IsDefinedExpression, IsTrueExpression, FunctionCall, MethodCall, PointerCall, AddArrayExpression, BinaryExpression, TernaryExpression, AssignExpression, NegateExpression, NotExpression, ComplementExpression, IncrementExpression, DecrementExpression

Every node carries a kind string discriminator and loc with source positions.

Full node reference: AST.md

GSC Features Supported

Declarations

• #include, #using_animtree
• Function declarations with parameters
• Constants (name = value;)

Statements

• if / else, while, do/while, for, foreach
• switch / case / default
• return, break, continue
• wait, waitframe, waittillframeend
• endon, notify, waittill, waittillmatch
• thread, childthread call modifiers
• breakpoint, prof_begin, prof_end
• assert, assertex, assertmsg
• Dev blocks (/# ... #/)

Expressions

• All arithmetic, comparison, logical, bitwise operators
• Ternary operator
• All assignment operators (=, +=, -=, *=, /=, %=, <<=, >>=, |=, &=, ^=)
• Increment/decrement (prefix and postfix)
• Function calls (local, qualified, builtin)
• Method calls (space-separated)
• Pointer calls ([[func]](args))
• Field access (.field), .size
• Array access (arr[key])
• Vectors ((x, y, z))
• Arrays ([1, 2, 3]), empty arrays ([])
• Tuples ([a, b] = func())
• Animation references (%animname)
• Localized strings (&"text")
• Hash literals (#"string")
• isdefined(), istrue()
• Globals: self, level, game, anim, thisthread, undefined, true, false

Preprocessor

• #define (plain, object-like, function-like macros)
• #undef
• #if / #ifdef / #ifndef / #elif / #elifdef / #elifndef / #else / #endif
• #include / #inline
• #using_animtree
• Macro expansion with # (stringify) and ## (paste)
• Built-in macros: __FILE__, __LINE__, __DATE__, __TIME__

Lexer

• All operators and punctuation
• Integer literals (decimal, hex 0x, binary 0b, octal 0o)
• Float literals (with f suffix, scientific notation)
• Digit separators (1'000)
• String literals with escape sequences
• Localized strings (&"...")
• Path identifiers (anim\battlechatter → normalized to anim/battlechatter)
• Line continuation (\ before newline)
• Comments (//, /* */, /@ @/)

Performance

Tested on 2,085 real T6 scripts (25 MB total):

| Metric | Value | |--------|-------| | Total parse time | 2.83s | | Average per file | 1.36ms | | Largest file parsed | 208 KB | | Total AST nodes | 3.6M |

License

MIT