Skip to content

Commit 112c563

Browse files
AvarianKnightAvarianKnight
committed
fix protos
1 parent 592f204 commit 112c563

2 files changed

Lines changed: 208 additions & 6 deletions

File tree

‎CLAUDE.md‎

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
# NativeCodeGen - Claude Context
2+
3+
Always use /tmp/nativegen for putting your generated builds
4+
5+
## Project Overview
6+
7+
NativeCodeGen is a code generator for RDR3 (Red Dead Redemption 3) and FiveM/RedM native functions. It parses MDX files containing native function definitions and generates TypeScript, Lua, JSON, and Protobuf outputs.
8+
9+
## Project Structure
10+
11+
```
12+
NativeCodeGen/
13+
├── src/
14+
│ ├── NativeCodeGen.Cli/ # CLI application
15+
│ │ ├── Program.cs # Entry point, command parsing
16+
│ │ └── TrimmerRoots.xml # Types to preserve for AOT/trimming
17+
│ ├── NativeCodeGen.Core/ # Core library
18+
│ │ ├── Export/ # Exporters for different formats
19+
│ │ │ ├── IExporter.cs # Exporter interface + ExportOptions
20+
│ │ │ ├── ICodeGenerator.cs # Code generator interface + GeneratorOptions
21+
│ │ │ ├── BaseExporter.cs # Base class for code exporters
22+
│ │ │ ├── JsonExporter.cs # JSON output
23+
│ │ │ ├── ProtobufExporter.cs # Protobuf binary output
24+
│ │ │ ├── DatabaseConverter.cs # Converts parsed models to export models
25+
│ │ │ ├── ExportModels.cs # Export DTOs with protobuf attributes
26+
│ │ │ ├── JsonContext.cs # JSON source generator context
27+
│ │ │ └── natives.proto # Protobuf schema definition
28+
│ │ ├── Generation/ # Code generation utilities
29+
│ │ │ ├── CodeBuilder.cs # String builder with indentation
30+
│ │ │ ├── RawNativeBuilder.cs # Raw function generation (TS/Lua)
31+
│ │ │ ├── ArgumentBuilder.cs # Native invoke argument building
32+
│ │ │ ├── NativeClassifier.cs # Classifies natives into handle classes
33+
│ │ │ ├── SharedClassGenerator.cs # Generates handle/namespace classes
34+
│ │ │ ├── SharedStructGenerator.cs # Generates struct classes
35+
│ │ │ └── SharedEnumGenerator.cs # Generates enum definitions
36+
│ │ ├── Models/ # Data models
37+
│ │ │ ├── NativeDefinition.cs # Native function definition
38+
│ │ │ ├── NativeParameter.cs # Function parameter with flags
39+
│ │ │ ├── TypeInfo.cs # Type information + categorization
40+
│ │ │ ├── EnumDefinition.cs # Enum with members
41+
│ │ │ ├── StructDefinition.cs # Struct with fields
42+
│ │ │ ├── SharedExample.cs # Shared code examples
43+
│ │ │ ├── Callout.cs # Note/warning callouts
44+
│ │ │ └── Flags.cs # ParamFlags, FieldFlags enums
45+
│ │ ├── Parsing/ # MDX/C parsing
46+
│ │ │ ├── MdxParser.cs # Main MDX file parser
47+
│ │ │ ├── MdxComponentParser.cs # Bracket syntax parser [enum: X]
48+
│ │ │ ├── FrontmatterParser.cs # YAML frontmatter parser
49+
│ │ │ ├── SignatureParser.cs # C-style signature parser
50+
│ │ │ ├── EnumParser.cs # C-style enum parser
51+
│ │ │ ├── StructParser.cs # C-style struct parser
52+
│ │ │ └── CLexer.cs # C tokenizer
53+
│ │ ├── Registry/ # Type registries
54+
│ │ │ ├── EnumRegistry.cs # Enum definitions lookup
55+
│ │ │ ├── StructRegistry.cs # Struct definitions lookup
56+
│ │ │ └── SharedExampleRegistry.cs # Shared examples lookup
57+
│ │ ├── TypeSystem/ # Type mapping
58+
│ │ │ ├── ITypeMapper.cs # Type mapper interface
59+
│ │ │ ├── TypeMapperBase.cs # Base implementation
60+
│ │ │ └── LanguageConfig.cs # Language-specific config
61+
│ │ └── Utilities/ # Helpers
62+
│ │ ├── NameConverter.cs # Name transformations
63+
│ │ └── NameDeduplicator.cs # Deduplication logic
64+
│ ├── NativeCodeGen.TypeScript/ # TypeScript generator
65+
│ │ ├── TypeScriptExporter.cs # Main exporter
66+
│ │ ├── Generation/
67+
│ │ │ ├── TypeScriptGenerator.cs # Generates TS files
68+
│ │ │ ├── TypeScriptEmitter.cs # Language-specific emission
69+
│ │ │ └── TypeScriptTypeMapper.cs # TS type mapping
70+
│ └── NativeCodeGen.Lua/ # Lua generator (similar structure)
71+
├── tests/
72+
│ └── NativeCodeGen.Tests/ # Unit tests
73+
├── packages/ # Generated npm packages (WIP)
74+
└── esbuild-plugin/ # esbuild tree-shaking plugin
75+
```
76+
77+
## Key Concepts
78+
79+
### MDX File Format
80+
Native definitions are in MDX files with:
81+
- YAML frontmatter: `ns` (namespace), `aliases`, `apiset`
82+
- Heading with native name: `## NATIVE_NAME`
83+
- C-style signature in code block
84+
- Description, parameters, return value sections
85+
86+
### Bracket Syntax
87+
- `[enum: EnumName]` - Reference to enum
88+
- `[struct: StructName]` - Reference to struct
89+
- `[native: NativeName]` or `[native: NativeName | gta5]` - Reference to native (with optional game)
90+
- `[example: ExampleName]` - Reference to shared example
91+
- `[note: Description]` or `[note: Title | Description]` - Note callout
92+
- `[warning: ...]`, `[info: ...]`, `[danger: ...]` - Other callout types
93+
94+
### Type Categories (TypeInfo.cs)
95+
- `Void`, `Primitive`, `Handle`, `Hash`, `String`, `Vector3`, `Any`, `Struct`, `Enum`
96+
97+
### Parameter Flags (ParamFlags)
98+
- `None`, `Output`, `This`, `NotNull`, `In`
99+
- `Output` = pointer output (int*, float*, Vector3*)
100+
- `In` = input+output pointer (@in attribute)
101+
- `This` = instance method receiver (@this attribute)
102+
103+
### Binding Styles (RawNativeBuilder)
104+
- `Global` - `globalThis.X = function()` (no tree-shaking)
105+
- `Export` - `export function X()` (tree-shakeable)
106+
- `Module` - `ModuleName.X = function()`
107+
108+
### Generation Modes
109+
1. **Class-based** (default): Generates handle classes (Entity, Ped, Vehicle) and namespace utilities
110+
2. **Raw**: Generates plain functions per namespace file
111+
3. **Single-file**: All natives in one file (requires --raw)
112+
4. **Package**: Complete npm package with esbuild plugin (WIP)
113+
114+
## CLI Commands
115+
116+
```bash
117+
# Generate TypeScript (class-based)
118+
nativegen generate -i <input> -o <output> -f typescript
119+
120+
# Generate raw functions
121+
nativegen generate -i <input> -o <output> -f typescript --raw
122+
123+
# Generate single file with exports (tree-shakeable)
124+
nativegen generate -i <input> -o <output> -f typescript --raw --single-file --exports
125+
126+
# Generate JSON database
127+
nativegen generate -i <input> -o <output>/natives.json -f json
128+
129+
# Generate Protobuf binary
130+
nativegen generate -i <input> -o <output>/natives.bin -f proto
131+
132+
# Validate only
133+
nativegen validate -i <input>
134+
```
135+
136+
## Important Implementation Details
137+
138+
### Trimmer/AOT Compatibility
139+
- Uses `TrimmerRoots.xml` to preserve reflection-based types
140+
- Must add any YamlDotNet-deserialized classes (Frontmatter, SharedExampleFrontmatter)
141+
- Must add protobuf-net serialized classes (Export* classes)
142+
143+
### Enum Value Generation
144+
- C-style: unassigned members get `previous + 1`
145+
- Handles negative start values (e.g., eVehicleSeat starts at -2)
146+
- Parses hex values for incrementing
147+
148+
### JSON Output Structure
149+
- Flat `natives` array (each with `ns` field)
150+
- `enums`, `structs`, `sharedExamples` as dictionaries keyed by name
151+
- `types` for type definitions
152+
153+
### Protobuf Output
154+
- Uses protobuf-net for serialization
155+
- Schema in `natives.proto`
156+
- Binary output for efficient parsing
157+
158+
## Current Work in Progress
159+
160+
1. **--package flag**: Generate complete npm package with:
161+
- package.json
162+
- esbuild plugin for tree-shaking
163+
- Build scripts
164+
- Generated natives with `export function` style
165+
166+
2. **esbuild plugin**: Auto-import used natives for tree-shaking without explicit imports
167+
168+
## Testing
169+
170+
```bash
171+
dotnet test # Run all tests
172+
dotnet test --filter "ClassName" # Run specific test class
173+
```
174+
175+
## Building
176+
177+
```bash
178+
dotnet build # Debug build
179+
dotnet publish src/NativeCodeGen.Cli -c Release -r linux-x64 --self-contained # Release
180+
```
181+
182+
## Related Repositories
183+
184+
- `rdr3-natives`: MDX native definitions for RDR3
185+
- Input expected at: `code/enums/`, `code/structs/`, `code/shared-examples/`, and namespace directories

‎src/NativeCodeGen.Core/Export/natives.proto‎

Lines changed: 23 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,28 @@ message Database {
2626
repeated Enum enums = 2;
2727
repeated Struct structs = 3;
2828
repeated SharedExample shared_examples = 4;
29+
repeated TypeEntry types = 5;
30+
}
31+
32+
enum TypeCategory {
33+
TYPE_PRIMITIVE = 0;
34+
TYPE_HANDLE = 1;
35+
TYPE_HASH = 2;
36+
TYPE_VECTOR3 = 3;
37+
TYPE_STRING = 4;
38+
TYPE_VOID = 5;
39+
TYPE_ANY = 6;
40+
}
41+
42+
message TypeInfo {
43+
TypeCategory category = 1;
44+
optional string native_type = 2;
45+
optional string description = 3;
46+
}
47+
48+
message TypeEntry {
49+
string name = 1;
50+
TypeInfo type = 2;
2951
}
3052

3153
message Namespace {
@@ -71,7 +93,7 @@ message EnumMember {
7193
message Struct {
7294
string name = 1;
7395
repeated StructField fields = 2;
74-
repeated NativeReference used_by_natives = 3;
96+
repeated string used_by_natives = 3;
7597
optional int32 default_alignment = 4;
7698
}
7799

@@ -85,11 +107,6 @@ message StructField {
85107
optional int32 alignment = 7;
86108
}
87109

88-
message NativeReference {
89-
string name = 1;
90-
string hash = 2;
91-
}
92-
93110
message SharedExample {
94111
string name = 1;
95112
string title = 2;

0 commit comments

Comments
 (0)