@needle-tools/needle-component-compiler 2.4.0-pre → 3.0.0-68ab237

package/Changelog.md

@@ -1,85 +1,184 @@
-# Changelog
-All notable changes to this package will be documented in this file.
-
-The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
-and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
-
-## [2.4.0-pre] - 2022-11-22
-# 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.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
-
-## [1.7.0] - 2022-07-14
-- change: skip non-serializeable variables (private without ``@serializable``)
-- improve member type generation
-- fix bug in type generation for array types
-- add/improve initial assignment codegen for object types
-
-## [1.6.3] - 2022-07-12
-- add warning when class type is unknown
-
-## [1.6.2] - 2022-07-11
-- fix ``@type`` for class declaration
-
-## [1.6.1] - 2022-07-10
-- add using ``types.json`` json file that will be generated from Unity
-- change ``@type`` annotiation to only work without braces to be consistent
-
-## [1.5.0] - 2022-07-07
-- change ``@type`` annotation to work with and without braces (e.g. ``@type My.Type`` or ``@type (My.Type)``)
-
-## [1.4.0] - 2022-07-06
-- add CODEGEN_START and END sections to allow adding code before or after a generated componnet
-- add ``@ifdef`` to ifdef fields 
-
-## [1.3.0] - 2022-06-27
-- add support for typescript namespace
-
-## [1.2.1] - 2022-06-15
-- allow adding ``@type(MyNamespace.MyType)`` to class declaration
-
-## [1.1.0] - 2022-06-13
-- add ``@type(MyNamespace.MyType)`` decorator for fields to specifiy C# type
-- add minimal docs to readme
-- dont emit comments anymore
-- make created classes partial
-
-## [1.0.1] - 2022-05-29
-- disable all warnings for generated scripts
-- add mesh and texture types
-
-## [1.0.0] - 2022-04-22
+# Changelog
+All notable changes to this package will be documented in this file.
+
+The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
+and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
+
+## [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
+
+## [1.7.0] - 2022-07-14
+- change: skip non-serializeable variables (private without ``@serializable``)
+- improve member type generation
+- fix bug in type generation for array types
+- add/improve initial assignment codegen for object types
+
+## [1.6.3] - 2022-07-12
+- add warning when class type is unknown
+
+## [1.6.2] - 2022-07-11
+- fix ``@type`` for class declaration
+
+## [1.6.1] - 2022-07-10
+- add using ``types.json`` json file that will be generated from Unity
+- change ``@type`` annotiation to only work without braces to be consistent
+
+## [1.5.0] - 2022-07-07
+- change ``@type`` annotation to work with and without braces (e.g. ``@type My.Type`` or ``@type (My.Type)``)
+
+## [1.4.0] - 2022-07-06
+- add CODEGEN_START and END sections to allow adding code before or after a generated componnet
+- add ``@ifdef`` to ifdef fields 
+
+## [1.3.0] - 2022-06-27
+- add support for typescript namespace
+
+## [1.2.1] - 2022-06-15
+- allow adding ``@type(MyNamespace.MyType)`` to class declaration
+
+## [1.1.0] - 2022-06-13
+- add ``@type(MyNamespace.MyType)`` decorator for fields to specifiy C# type
+- add minimal docs to readme
+- dont emit comments anymore
+- make created classes partial
+
+## [1.0.1] - 2022-05-29
+- disable all warnings for generated scripts
+- add mesh and texture types
+
+## [1.0.0] - 2022-04-22
 - initial release

package/Readme.md

@@ -1,19 +1,134 @@
-## Typescript to Unity component
-
-Little helper package to transpile typescript files to Unity C# components.  
-Please run ``npm install`` first before using.
-
-### Usage
-``node <path to>/component-compiler.js <output_directory> <path_to/my_script.ts>``
-
-
-### Command decorators
-- ``@dont-generate-component`` add before class to skip generating a component
-- ``@generate-component`` to enforce generating a component (not required)
-- ``@serializeField`` field decorator, similar to ``[SerializeField]`` in Unity
-- ``@nonSerialized`` field or method decorator to skip generating c# code for a field or a method, similar to ``[NonSerialized]`` in Unity
-- ``@type MyNamespace.MyType`` decorator for fields or classes, specifiy C# type of field or class
-- ``@ifdef MY_IFDEF`` field decorator only at the moment
-
-### Test
-- Run single test: `` npm run test:single -- -r ts-node/register "./test/blender/blender.from_typedef.test.ts"``
+## Needle Engine Component Compiler
+
+Compiles TypeScript component definitions into **Unity C#** component stubs and **Blender** Python component schemas for Needle Engine.
+
+### Quick Start
+
+No install required — run directly with `npx`:
+
+```bash
+npx @needle-tools/needle-component-compiler <target> <output_dir> <input_files...>
+```
+
+| Argument | Description |
+|---|---|
+| `target` | `csharp` or `blender` |
+| `output_dir` | Directory for generated files |
+| `input_files` | One or more `.ts` source files (globs supported) |
+
+#### Examples
+
+```bash
+# Generate C# component stubs
+npx @needle-tools/needle-component-compiler csharp ./codegen ./src/MyComponent.ts
+
+# Generate Blender component schemas
+npx @needle-tools/needle-component-compiler blender ./codegen ./src/MyComponent.ts
+
+# Process multiple files
+npx @needle-tools/needle-component-compiler csharp ./codegen ./src/**/*.ts
+
+# Print version
+npx @needle-tools/needle-component-compiler --version
+```
+
+### Programmatic API
+
+```
+npm install @needle-tools/needle-component-compiler
+```
+
+```ts
+import { Compiler, CSharpWriter, FileSink } from "@needle-tools/needle-component-compiler";
+
+const sink = new FileSink("./output");
+const writer = new CSharpWriter(sink);
+const compiler = new Compiler();
+compiler.compile(writer, code, "MyComponent.ts");
+```
+
+### Supported TypeScript Features
+
+- Classes extending `Behaviour`, `MonoBehaviour`, or implementing `IComponent`
+- Public, protected, and private fields with type annotations
+- Default values (primitives, `new` expressions, literals)
+- Array types: `T[]`, `Array<T>`
+- Union types (nullable types like `Object3D | null` resolve to the concrete type)
+- Enums (with value initialization)
+- Methods with parameters and return types
+- Destructured parameters (compiled as `object`)
+
+### Comment Directives
+
+Use `//` comments above classes, fields, or methods to control code generation:
+
+| Directive | Target | Description |
+|---|---|---|
+| `@generate-component` | Class | Force generation (not required, classes are generated by default) |
+| `@dont-generate-component` | Class | Skip generating this class entirely |
+| `@type MyNamespace.MyType` | Class / Field | Override the resolved C# type or base class |
+| `@abstract` | Class | Mark the generated class as `abstract` |
+| `@serializeField` | Field | Emit `[UnityEngine.SerializeField]` attribute |
+| `@nonSerialized` | Field / Method | Skip generating C# code for this member |
+| `@tooltip "My text"` | Field | Emit `[UnityEngine.Tooltip("My text")]` (C#) or `"description"` (Blender) |
+| `@contextmenu "Label"` | Method | Emit `[UnityEngine.ContextMenu("Label")]` |
+| `@ifdef MY_DEFINE` | Field | Wrap field in `#if MY_DEFINE` / `#endif` |
+
+### JSDoc Tooltips
+
+JSDoc comments (`/** ... */`) on fields are automatically converted to tooltips. The text is sanitized (inline code, URLs, images, and JSDoc tags are stripped) to produce clean tooltip text.
+
+```ts
+export class MyComponent extends Behaviour {
+    /** The movement speed of the character */
+    public speed: number = 5;
+}
+```
+
+**C# output:**
+```csharp
+[UnityEngine.Tooltip("The movement speed of the character")]
+public float @speed = 5f;
+```
+
+**Blender output:**
+```json
+"speed": {
+    "type": "float",
+    "value": 5,
+    "description": "The movement speed of the character"
+}
+```
+
+An explicit `// @tooltip` directive takes priority over a JSDoc comment on the same field.
+
+### Codegen Fences
+
+Generated C# files are wrapped in codegen fences:
+
+```csharp
+// NEEDLE_CODEGEN_START
+// auto generated code - do not edit directly
+
+#pragma warning disable
+
+namespace Needle.Typescript.GeneratedComponents
+{
+    public partial class MyComponent : UnityEngine.MonoBehaviour
+    {
+        public float @speed = 5f;
+    }
+}
+
+// NEEDLE_CODEGEN_END
+```
+
+This allows you to add custom code outside the fences that will be preserved when the file is regenerated.
+
+# Contact ✒️
+<b>[🌵 Needle](https://needle.tools)</b> •
+[Github](https://github.com/needle-tools) •
+[Twitter](https://twitter.com/NeedleTools) •
+[Discord](https://discord.needle.tools) •
+[Forum](https://forum.needle.tools) •
+[Youtube](https://youtube.com/@needle-tools)

package/dist/BaseWriter.d.ts

@@ -0,0 +1,23 @@
+import { Argument, CodeTextWriter, EnumMember, ISink, IWriter, Visibility } from "./base-compiler";
+import { TypeSourceInformation } from "./register-types";
+export declare abstract class BaseWriter implements IWriter {
+    private _sink?;
+    protected writer: CodeTextWriter;
+    get sink(): ISink;
+    constructor(_sink?: ISink);
+    /** Enum registry: lowercased enum name → members */
+    protected _enumRegistry: Map<string, EnumMember[]>;
+    registerEnum(name: string, members: EnumMember[]): void;
+    abstract resolveCSharpTypeName(typescriptTypeName: string, baseTypes?: string[]): string | void;
+    abstract startNewType(filePath: string, typeName: string, baseType: string[], comments?: string[]): boolean | void;
+    abstract endNewType(filePath: string, typeName: string): void;
+    abstract writeMember(visibility: Visibility, name: string, isArray: boolean, type: string, initialValue?: string, comments?: string[]): void;
+    abstract writeMethod(visibility: Visibility, name: string, returnType: string, args: Argument[], comments: string[]): void;
+    abstract writeNewTypeExpression(typeName: string, args?: string[]): void;
+    private _currentlyProcessingFiles;
+    get outputInfo(): TypeSourceInformation;
+    private _createdSchemesPerFile;
+    begin(filePath: string | null): void;
+    end(filePath: string | null): void;
+    protected writeScheme(processingFilePath: string | null, component: string): void;
+}

package/dist/BaseWriter.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseWriter = void 0;
+var fs_1 = require("fs");
+var base_compiler_1 = require("./base-compiler");
+var commands_1 = require("./commands");
+var BaseWriter = /** @class */ (function () {
+    function BaseWriter(_sink) {
+        this._sink = _sink;
+        this.writer = new base_compiler_1.CodeTextWriter();
+        /** Enum registry: lowercased enum name → members */
+        this._enumRegistry = new Map();
+        this._currentlyProcessingFiles = {};
+        this._createdSchemesPerFile = {};
+    }
+    Object.defineProperty(BaseWriter.prototype, "sink", {
+        get: function () {
+            return this._sink;
+        },
+        enumerable: false,
+        configurable: true
+    });
+    BaseWriter.prototype.registerEnum = function (name, members) {
+        this._enumRegistry.set(name.toLowerCase(), members);
+    };
+    Object.defineProperty(BaseWriter.prototype, "outputInfo", {
+        get: function () {
+            return this._createdSchemesPerFile;
+        },
+        enumerable: false,
+        configurable: true
+    });
+    BaseWriter.prototype.begin = function (filePath) {
+        this._enumRegistry.clear();
+        if (!this._currentlyProcessingFiles[filePath]) {
+            this._currentlyProcessingFiles[filePath] = [];
+        }
+    };
+    BaseWriter.prototype.end = function (filePath) {
+        var results = this._currentlyProcessingFiles[filePath];
+        console.log("Writing schemes for", filePath, results);
+        if (results) {
+            var previousResultsFromThisFile = this._createdSchemesPerFile[filePath];
+            if (previousResultsFromThisFile) {
+                for (var _i = 0, previousResultsFromThisFile_1 = previousResultsFromThisFile; _i < previousResultsFromThisFile_1.length; _i++) {
+                    var previouslyCreated = previousResultsFromThisFile_1[_i];
+                    var foundInAny = false;
+                    for (var _a = 0, results_1 = results; _a < results_1.length; _a++) {
+                        var res = results_1[_a];
+                        if (res.filePath === previouslyCreated.filePath) {
+                            foundInAny = true;
+                            break;
+                        }
+                    }
+                    if (!foundInAny) {
+                        for (var sourcePath in this._createdSchemesPerFile) {
+                            if (foundInAny)
+                                break;
+                            if (sourcePath === filePath)
+                                continue;
+                            var otherSourceSchemes = this._createdSchemesPerFile[sourcePath];
+                            if (otherSourceSchemes.includes(previouslyCreated)) {
+                                // the file was moved to another source file
+                                foundInAny = true;
+                            }
+                        }
+                    }
+                    if (!foundInAny && (0, fs_1.existsSync)(previouslyCreated.filePath)) {
+                        (0, fs_1.unlinkSync)(previouslyCreated.filePath);
+                        (0, commands_1.sendFileDeletedCommand)(previouslyCreated.filePath);
+                    }
+                }
+            }
+            this._createdSchemesPerFile[filePath] = results;
+        }
+        delete this._currentlyProcessingFiles[filePath];
+    };
+    BaseWriter.prototype.writeScheme = function (processingFilePath, component) {
+        var res = this.sink.flush(component + ".component.json", this.writer.flush());
+        // if an output path is returned it means a file has been written to that path
+        if (res && (0, fs_1.existsSync)(res)) {
+            (0, commands_1.sendFileWrittenCommand)(res);
+            // add the scheme to the list of created schemes
+            if (processingFilePath && this._currentlyProcessingFiles[processingFilePath]) {
+                this._currentlyProcessingFiles[processingFilePath].push({ componentName: component, filePath: res });
+            }
+        }
+    };
+    return BaseWriter;
+}());
+exports.BaseWriter = BaseWriter;

package/dist/Compiler.d.ts

@@ -0,0 +1,22 @@
+import { IWriter } from "./base-compiler";
+/** Typescript Walker */
+export declare class Compiler {
+    compile(writer: IWriter, code: string, sourceFilePath: string | null): void;
+    private run;
+    private visitEnumDeclaration;
+    private visit;
+    private visitClassDeclaration;
+    private visitPropertyDeclaration;
+    private visitMethodDeclaration;
+    private resolveParameters;
+    private debugLog;
+    private getComments;
+    /** Strip markdown/code/images/URLs/JSDoc tags to produce a plain-text tooltip */
+    private static sanitizeJsdocForTooltip;
+    private getVisibility;
+    private tryResolveTypeFromExpression;
+    private resolveType;
+    private resolveTypeFromString;
+    private isArrayType;
+    private resolveExpression;
+}