Skip to content

feat(player): give SpriteStudioPlayer2D real enums and ClassDB properties - #259

Merged
Naruto merged 1 commit into
developfrom
feature/player-enums-and-classdb-properties
Aug 3, 2026
Merged

feat(player): give SpriteStudioPlayer2D real enums and ClassDB properties#259
Naruto merged 1 commit into
developfrom
feature/player-enums-and-classdb-properties

Conversation

@Naruto

@Naruto Naruto commented Aug 3, 2026

Copy link
Copy Markdown
Collaborator

What

Registers the two halves of SpriteStudioPlayer2D's public surface that never reached ClassDB: the enums behind its int parameters, and the inspector properties.

Enums

set_playback_direction, set_part_color_override* and set_part_cell_override took plain ints documented only in a comment. Four enums are added and taken as parameter types, and bound alongside the existing AnimationProcessMode:

enum constants
AnimationProcessMode ANIMATION_PROCESS_PHYSICS / _IDLE
PlaybackDirection PLAYBACK_DIRECTION_FORWARD / _BACKWARD
PlaybackStyle PLAYBACK_STYLE_NORMAL / _PING_PONG
ColorBlendOperation COLOR_BLEND_MIX / _MUL / _ADD / _SUB
OverridePriority OVERRIDE_PRIORITY_NEXT_KEYFRAME / _UNTIL_ANIMATION_CHANGE / _PERMANENT

Values follow the runtime's FFI encoding (ss_runtime_set/get_playback_direction normalizes direction and style to 0/1 on both sides, so these are not the Rust PlaybackDirection discriminants; blend_op and priority_mode match ssruntime.h). DEFVAL now names the default instead of spelling 0 / 1.

Bug fixed along the way: AnimationProcessMode's two constants were already registered via BIND_CONSTANT (constants with no enum). That collided with BIND_ENUM_CONSTANTClass 'SpriteStudioPlayer2D' already has constant 'ANIMATION_PROCESS_PHYSICS' — and kept the enum out of ClassDB, even though doc_classes/ already described the property as enum="SpriteStudioPlayer2D.AnimationProcessMode". The old binding is dropped.

Properties

Only ssab was registered; the other 17 came from _set / _get / _get_property_list, so they were invisible to ClassDB.class_get_property_list, to the doc tooling, and to any binding generator. They move to ADD_PROPERTY / ADD_GROUP, with the three genuinely instance-dependent hints — the animation name list and the frame / section ranges — injected through _validate_property, the same pattern SpriteStudioPartAttachment2D already uses for part_name.

  • cellmaps/* stays in _get_property_list: both its count and its names come from the resource.
  • frame_rate / playback_direction / playback_style stay in _set / _get — reachable by name, deliberately absent from the property list, and already covered by bound accessors.
  • set_animation_section_start / set_animation_section_end are added because ADD_PROPERTY needs single-argument setters. set_animation_section(start, end) is unchanged.

Compatibility

Names, order, hints and usage flags are unchanged — including frame's editor-only usage — so existing scenes keep loading and the inspector looks the same. GDScript passing raw ints to the now-enum parameters still compiles.

One visible difference: ADD_PROPERTY lets Godot resolve default values, so a re-saved scene omits properties left at their default instead of writing all 17. Verified by packing and saving a scene:

=== all-default player ===
[node name="Player" type="SpriteStudioPlayer2D" parent="." unique_id=2105169513]

=== modified player ===
[node name="Player" type="SpriteStudioPlayer2D" parent="." unique_id=246106748]
speed_scale = 2.0
flip_h = true

Test plan

  • ./scripts/build-extension.sh target=editor (macOS arm64) — builds and links
  • ./scripts/build.sh target=editor (macOS arm64, custom module) — builds and links
  • Headless ClassDB inspection against the module build:
    • all 5 enums appear in class_get_enum_list with the expected constants
    • class_get_property_list reports the 17 properties + 4 groups in the original order, with the original hints and usage flags (frame still PROPERTY_USAGE_EDITOR only)
    • _validate_property injects the live hints: animation'Arrow_Attack', frame'0,70.0,0.01', section → '0,70.0,1'
    • round trip on frame_rate, direction/style, section endpoints, animation_process_mode, and set_part_color_override with default arguments
  • doc_classes/SpriteStudioPlayer2D.xml compiles into doc_data.gen.cpp

Runtime behaviour of the GDExtension build was not exercised separately — it shares _bind_methods with the module build, and ADD_GROUP / _validate_property already have working precedent in both builds via SpriteStudioPartAttachment2D.

Docs

doc_classes/SpriteStudioPlayer2D.xml gains the new constants and the two section members; the value tables in docs/{en,ja}/api/player.md and docs/{en,ja}/workflow/usage_scripting.md now name the constants next to the numbers.

…ties

Two parts of the player's public surface were never registered with ClassDB,
so anything that reads the class description - the inspector's own metadata,
ClassDB.class_get_property_list, the doc tooling, and any future binding
generator - could not see them.

Enums. set_playback_direction, set_part_color_override* and
set_part_cell_override took plain ints whose meaning existed only in a comment
above the declarations. Add PlaybackDirection, PlaybackStyle,
ColorBlendOperation and OverridePriority, take them as parameter types, and
bind them alongside the existing AnimationProcessMode. The values follow the
runtime's FFI encoding, which normalizes direction and style to 0/1 on both
sides of the boundary, so they are not the Rust PlaybackDirection
discriminants. DEFVAL now names the default instead of spelling 0 and 1.

While binding them: AnimationProcessMode's two constants were already
registered with BIND_CONSTANT, as constants with no enum. That collided with
BIND_ENUM_CONSTANT ("Class 'SpriteStudioPlayer2D' already has constant") and
kept the enum itself out of ClassDB, even though doc_classes already described
the property as enum="SpriteStudioPlayer2D.AnimationProcessMode". Drop the old
binding.

Properties. Only `ssab` was registered; the other seventeen were served from
_set / _get / _get_property_list. Move them to ADD_PROPERTY / ADD_GROUP and
inject the three hints that genuinely depend on the instance - the animation
name list and the frame / section ranges - through _validate_property, the
same pattern SpriteStudioPartAttachment2D already uses for part_name.
`cellmaps/*` stays in _get_property_list because both its count and its names
come from the resource. frame_rate, playback_direction and playback_style stay
in _set / _get: they are reachable by name but deliberately absent from the
property list, and they already have bound accessors.

The section endpoints needed single-argument setters to be properties, so
set_animation_section_start / set_animation_section_end join the existing
set_animation_section.

Names, order, hints and usage flags are unchanged - including frame's
editor-only usage - so existing scenes keep loading and the inspector looks
the same. One visible difference: ADD_PROPERTY lets Godot resolve default
values, so a re-saved scene omits properties left at their default instead of
writing all seventeen.
@Naruto
Naruto merged commit 153b17d into develop Aug 3, 2026
0 of 2 checks passed
@Naruto
Naruto deleted the feature/player-enums-and-classdb-properties branch August 3, 2026 15:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant