[dexterBEN]

Problem

@GodotProperty supports a custom property name but does not allow scripts to specify hint or hintString.

The generator already infers hints for certain types, such as Node subclasses, Resources, and typed lists. However, users cannot customize these hints or provide additional inspector settings, such as a numeric range.

Although PropertyInfo already supports both fields, there is no way to configure them through the annotation.

Proposed solution

Add optional hint and hintString parameters to GodotProperty and update the generator to pass them to the generated DartPropertyInfo.

For example:

@GodotProperty(
  hint: PropertyHint.range,
  hintString: '0,1000,10',
)
int speed = 400;

This provides Godot with the metadata needed to display a numeric range from 0 to 1000 with a step of 10 in the inspector.

Each parameter overrides its corresponding inferred value independently:

• Omitting both parameters preserves the existing automatic hints.
• Providing only one parameter preserves the inferred value of the other.
• PropertyHint.none explicitly disables an inferred hint.
• An empty hintString explicitly clears the inferred string.

The generator also escapes hint strings so quotes, backslashes, dollar signs, and control characters are preserved safely in the generated Dart code.

Existing annotations remain compatible without changes.

Validation

Automated tests

Added 9 tests that run the actual builder and verify:

• Explicit hints and hint strings are exported.
• Scalar properties without hints retain their defaults.
• Automatic hints for Node subclasses and typed lists are preserved.
• Explicit values override inferred values, including PropertyHint.none and an empty hint string.
• Either parameter can be supplied independently.
• Annotations on getters support custom hints.
• Special characters survive generation without unintended interpolation.

The generated Dart is also checked for syntax errors.

All 9 tests pass. Static analysis passes for the generator and tests.

Run the tests from src/dart/godot_dart_build:

dart test test/property_hints_test.dart

The test command and a manual inspector verification procedure are documented in the package README.

Manual testing

2026-11-04.18-54-52.mp4

Tested with Godot 4.4 on Linux, using the Compatibility renderer inside a DevContainer. The test project uses the local packages from this branch.

For Player.speed, configured with the range annotation shown above, verified that:

• The initial value is 400.
• Incrementing and decrementing changes the value by 10.
• The inspector restricts the value to the range 0–1000.
• Setting the value to 200, saving, closing, and reopening preserves the value.
• The game runs correctly, with a noticeable movement speed difference between values of 200 and 800.

Fixes #23