Component Compiler Changelog

@needle-tools/needle-component-compiler — Latest: 3.0.16

3.0.16 - 2026-03-24

Fixed

Fix array literal initializers (= [], = [1, 2, 3]) emitting C# 12 collection expressions not supported by Unity
- Empty arrays: initializer is omitted
- Non-empty primitive arrays: emit new float[] { 1f, 2f, 3f } syntax
- Non-empty non-primitive arrays: initializer is omitted

3.0.15 - 2026-03-23

Fixed

Fix non-void method stubs producing uncompilable C# (CS0161: not all code paths return a value) by emitting { return default; } instead of {}

3.0.14 - 2026-03-23

Fixed

Fix @type override on array fields producing double array suffix (e.g. Type[][] instead of Type[])
Map Euler to UnityEngine.Vector3 in C# output

3.0.12 - 2026-03-23

Fixed

Fix nullable array types (Texture[] | null, Array<Texture> | null, Array<Texture | null>) not emitting as arrays in C# and Blender output

3.0.5 - 2026-03-15

Added

--types <path> CLI flag to load external type mappings from a JSON file (e.g. Unity's Types.json)
@serializable() decorator on getter/setter accessors now generates C# fields, with deduplication when both getter and setter are decorated
Support for @type, @nonSerialized, and @serializeField comment directives on accessor properties

Fixed

Fix npx scoped package name resolution by changing bin to a string

3.0.3 - 2026-03-11

Fixed

Fix Promise<T> return types passing through as Promise instead of resolving to void
Fix unknown/web-only types (e.g. user-defined interfaces) in method parameters passing through instead of becoming object
Fix @nonSerialized comment directive not being respected on methods (only worked on fields before)
Fix void in union return types not being filtered out (e.g. void | boolean now correctly resolves to bool)
Fix enum types in method parameters and return types becoming object instead of preserving the enum name

Added

@type override on methods: // @type ReturnType overrides the return type, // @type paramName ParamType overrides a specific parameter's type

3.0.1 - 2026-03-04

Fixed

Fix string enum values being double-quoted in Blender output (e.g. "\"A\"" instead of "A")
Fix user-defined enums whose name collides with a built-in type (e.g. Color) being mapped to the built-in type instead of emitting as enum
Fix enum registry leaking across compilations, causing stale enum definitions from previous files to affect subsequent compilations

3.0.0 - 2026-03-04

Changed

Rewritten compiler architecture with a new Compiler (TypeScript walker) + IWriter (output backend) design, enabling pluggable output targets
CLI interface: needle-component-compiler <target> <output_dir> <input_files...> where target is csharp or blender

Added

Architecture

New BaseWriter / IWriter interface allows pluggable output backends (C#, Blender, and future targets like React Three Fiber)
New ISink / FileSink abstraction for output, with NEEDLE_CODEGEN_START / NEEDLE_CODEGEN_END fence support to preserve hand-written code sections
Standalone CLI (npx @needle-tools/needle-component-compiler) with --help and --version flags

C# Compiler

Enum declarations with numeric and string initializers
Union type fields (e.g. field: string | number) emit as object with a doc comment listing the union members
Inferred types from initializers (e.g. speed = 5 infers float, name = "hello" infers string, new Vector3() infers Vector3)
@dont-generate-component decorator to skip class generation
@nonSerialized support for fields (skips serialization)
@type override decorator for fields and classes
@tooltip decorator emits [Tooltip("...")] attribute
@serializable / @serializeField for private field serialization
@ifdef / #if UNITY_EDITOR wrapping for editor-only fields
NEEDLE_CODEGEN fences in generated output to preserve manual code sections
Static and abstract member handling (static fields skipped, static/abstract methods ignored)
Method return type emission (void, primitive types, mapped types)
Support for declare class with IComponent interface

Blender Compiler

Full Blender panel schema generation from TypeScript components
Property type mapping: number → FloatProperty, string → StringProperty, boolean → BoolProperty, enums → EnumProperty, arrays → CollectionProperty
Inferred types from initializers (numbers, strings, booleans, new expressions)
Enum support with EnumProperty items generation
@tooltip decorator maps to Blender description field
@nonSerialized decorator to skip properties
@dont-generate-component decorator to skip class generation
@type override decorator
Missing/unknown type handling with sensible defaults
register_types generation for Blender add-on registration
File watcher for automatic recompilation on source changes
Per-component output files with automatic cleanup on deletion

Fixed

Destructured method parameters (e.g. {xr}) now emit as object @obj instead of invalid object @{xr}
Object3D type correctly maps to UnityEngine.GameObject (not Transform)
new expression type inference for explicit types (e.g. new RGBAColor())
RGBAColor → Color automatic type mapping
Method inline anonymous type declarations (e.g. myMethod(arg: {x: number}))
Codegen no longer deletes manually added code outside of codegen sections
Output directory is created automatically if it doesn't exist

Testing

Comprehensive test suite with separate C# and Blender test runners (npm test, npm run test:csharp, npm run test:blender)
Test coverage for: basic fields, primitives, enums, unions, tooltips, inferred types, advanced features, codegen fences, methods, and extended type mappings

2.4.1-pre - 2023-04-03

Blender compiler

Add: typenames

2.4.0-pre - 2023-03-31

Blender compiler

Add: emit types from declared class implementing IComponent e.g. declare class MyComp implements IComponent

2.3.0-pre - 2022-11-22

Blender compiler

Add emit array
Add emit types by class name if unknown

2.2.0-pre.1 - 2022-11-13

Add: watcher now also generates the register_types file
Add: deleting code files now also deletes the generated files and reports it

2.1.0-pre - 2022-11-12

Add blender scheme compiler for creating and updating schemes (or removing them when the component gets deleted)

1.12.2 - 2025-06-06

Fix: Private fields decorated with @serializable() should be annotated with UnityEngine.SerializeField
Fix: Comment for // @serializeField should not affect subsequent fields

1.12.0 - 2025-06-02

Add: Support to serialize unknown classes when annotated with // @type object

1.11.2 - 2023-12-16

Fix: property setter emitting invalid C# code

1.11.1 - 2023-12-02

Fix: Use Unity AnimatorController type
Fix: method inline anonymous type declaration (e.g. myMethod(arg: {x:number}))

1.11.0 - 2023-11-18

Add: support to wrap fields with #if UNITY_EDITOR if their namespace contains UnityEditor
Add: more threejs types to generate Unity Material fields for

1.10.3 - 2023-09-08

Add: Needle Engine type RGBAColor is now automatically emitted as UnityEngine.Color

1.10.2 - 2023-09-08

Fix: @type was not properly applied for new expression cases (e.g. new RGBAColor should produce a new Color when decorated with @type Color)

1.10.1 - 2023-08-02

Add: use @tooltip to emit a UnityEngine.Tooltip
Update Readme

1.9.4 - 2023-05-24

Change: Object3D now emits GameObject field instead of Transform
Fix: ignore static methods
Fix: ignore abstract methods

1.9.3 - 2022-12-30

Add debug logs for when no file or target directory was passed in. Also wrapping core with try catch

1.9.2 - 2022-11-29

Fix codegen deleting code added manually outside of codegen sections
Fix codegen creating output directory if it does not exist yet

1.9.1 - 2022-11-05

Fix new Vector2(1, .5) generating invalid C# where number arguments were emitted as double instead of float

1.9.0 - 2022-10-18

Change: emit onEnable as OnEnable and onDisable as OnDisable so Unity creates component checkboxes
Change: ignore private and protected methods

1.8.0 - 2022-09-02

Add @nonSerialized decorator for fields and methods
Fix comment gen for unknown types

1.7.3 - 2022-09-02

Fix codegen for unknown array types
Fix codegen for abstract classes
Fix codegen for types imported as e.g. THREE.AnimationClip

1.7.2 - 2022-07-27

fix UnityEvent codegen

1.7.1 - 2022-07-25

fix array type codegen, for example scenes: Array<AssetReference> = [];, see issue https://github.com/needle-tools/needle-tiny-playground/issues/285