Implement the MVP Condition Registry

[AerunDev]

As a game developer
I want Pokémon Studio to expose the conditions required for the Event System MVP through a centralized Condition Registry
So that I can reproduce existing RPG Maker XP event logic without regressions and use the most common Pokémon-specific conditions

The Condition Registry is the declarative catalog of conditions available to the Condition Builder (see #780).

It defines which conditions exist and provides the metadata required to display, configure, validate, serialize and later interpret them. It does not manage the visual composition of conditions and does not execute gameplay logic.

The MVP must include:

• every condition required to replace RPG Maker XP's Conditional Branch command
• a limited set of Pokémon- and PSDK-specific conditions considered essential for common fangame workflows.

See #637 and the Wiki related page for further information.

The registry must remain extensible so that future condition domains can be added without modifying the Condition Builder itself.

Objectives

The MVP Condition Registry should:

• prevent regressions when migrating from RPG Maker XP
• expose the most common Pokémon fangame conditions
• centralize condition definitions and avoid hardcoded condition logic in the Condition Builder
• provide stable identifiers suitable for serialization
• make future condition additions predictable and maintainable.

Acceptance Criteria

Registry Architecture

• A centralized Condition Registry is available to the Condition Builder.
• The Condition Builder does not contain hardcoded knowledge of individual gameplay conditions.
• Conditions can be registered without modifying the structural logic of the Condition Builder.
• Registry entries are organized into functional categories.
• The registry exposes only conditions available in the current Pokémon Studio version.
• Condition definitions can be retrieved by their stable identifier.

Condition Definition Contract

Each registered condition defines at least:

• A stable technical identifier.
• A functional category identifier.
• A localized label key.
• A localized description or helper-text key when clarification is required.
• The supported comparison operators.
• The expected operand and value types.
• The value editor configuration required by the Condition Builder.
• Validation constraints.
• Serialization metadata.
• Any required editing context, such as the current event or project database.

Changing a display label must not invalidate existing serialized conditions.

Example structure:

{
  id: 'player.money',
  category: 'player',
  labelKey: 'eventConditions.player.money',
  operators: [
    'equal',
    'notEqual',
    'lessThan',
    'lessThanOrEqual',
    'greaterThan',
    'greaterThanOrEqual',
  ],
  value: {
    type: 'number',
    editor: 'numberInput',
    minimum: 0,
  },
}

The exact implementation may differ, provided the same responsibilities remain clearly separated.

MVP Condition Catalog

Variables

• Boolean Variable
• Numeric Variable
• Boolean Event Variable
• Numeric Event Variable

Legacy RPG Maker XP Switches and Self Switches are represented through boolean variables and boolean event variables.

String variables are not part of this ticket until their support is explicitly validated.

Event and Player Direction

• Player Facing Direction
• Event Facing Direction

Supported values:

• Up
• Down
• Left
• Right

Supported operators:

• is
• is not
• is one of
• is not one of

For an Event Facing Direction condition, the definition must also provide a way to select the targeted event.

Player

• Money

Supported operators:

• =
• ≠
• <
• ≤
• >
• ≥

The comparison value must support a literal number.
Comparison against another variable may be added only if it is covered by the MVP operand model.

Time

• Timer

Supported operators:

• =
• ≠
• <
• ≤
• >
• ≥

The editor must expose a readable duration while preserving the value format expected by the serialized condition.

Inventory

• Item Owned
• Item Quantity

Item Owned supports:

• has
• does not have

Item Quantity supports:

• =
• ≠
• <
• ≤
• >
• ≥

Both conditions must use project item references rather than free-form identifiers.

Input

• Input Key

The condition must reference configured input actions rather than physical keyboard keys when supported by PSDK.

Supported states for the MVP must cover the behavior required to replace RPG Maker XP.

At minimum:

• is pressed

Additional states such as is held or is released should only be included if runtime support is confirmed for the MVP.

Progression

• Badge Owned
• Badge Count

Badge Owned must reference the badge identifier or progression value used by the standard PSDK implementation.

Badge Count supports:

• =
• ≠
• <
• ≤
• >
• ≥

The implementation must avoid assuming that every project uses exactly eight badges.

Party

• Pokémon in Party
• Party Size

Pokémon in Party supports:

• contains
• does not contain

It must reference Pokémon species available in the project database.

Party Size supports:

• =
• ≠
• <
• ≤
• >
• ≥

The Registry must not hardcode a maximum party size of six.

Environment and Map

• Weather
• Current Map
• Player Terrain Tag
• Player System Tag

Weather supports:

• is
• is not
• is one of
• is not one of

Current Map must reference maps available in the project.

Player Terrain Tag and Player System Tag must reference the values available in the project configuration or PSDK data model.

Free-form values should not be used when structured project references are available.

Script

• Custom Script

The Custom Script condition allows advanced users to provide a Ruby expression expected to return a boolean result.

The definition must:

• expose an appropriate code editor
• explain that the expression must evaluate to true
• clearly identify the feature as advanced
• preserve the script content without transformation or information loss.

Pokémon Studio-side validation may verify that the field is not empty, but it is not expected to fully validate arbitrary Ruby code.

Operators

• Operators use stable technical identifiers independent from their displayed labels.
• Each condition exposes only the operators relevant to its data type and runtime behavior.
• Invalid condition / operator combinations cannot be produced through the registry.
• Operators are localized in the user interface.
• Multi-value operators expose an appropriate multi-value editor.

Example operator families:

Value type	Operators
Boolean	is true, is false
Number	=, ≠, <, ≤, >, ≥
Enum or reference	is, is not, is one of, is not one of
Ownership	has, does not have
Collection membership	contains, does not contain

Operator labels may vary by condition when a more natural wording improves comprehension.

Value Editors and References

• Each condition definition identifies the editor required to configure its value.
• Database references use searchable project-data selectors.
• Enum values use select or multi-select controls as appropriate.
• Numeric conditions use validated numeric inputs.
• Boolean conditions do not require users to enter raw true or false values.
• Duration conditions use a human-readable duration editor.
• Script conditions use a code-oriented text editor.

The registry defines the editor requirements, while the Condition Builder remains responsible for rendering the corresponding component.

Context-Dependent Conditions

Some conditions require contextual data.

Examples include:

• selecting an Event Variable
• selecting the event targeted by Event Facing Direction
• loading maps, items, Pokémon or tags from the current project.

For these conditions:

• Required context is declared by the condition definition.
• Missing context is handled explicitly.
• The Condition Builder receives user-friendly feedback when a condition cannot currently be configured.
• A missing database reference must not silently fall back to an unrelated value.

Validation

• Required values are identified by the registry.
• Numeric constraints are declared where relevant.
• Conditions cannot be considered complete while required operands are missing.
• References to unavailable project data are identified as invalid.
• Validation errors can be rendered by the Condition Builder using localized messages.
• Validation rules remain independent from visual component implementation.

Serialization Compatibility

• Every condition uses a stable identifier suitable for long-term serialization.
• Operators use stable identifiers.
• Values use predictable serialized structures.
• Localized labels are never used as stored identifiers.
• Serialized condition data can be resolved back to its registry definition.
• Unknown condition identifiers are reported explicitly.
• Renaming or reorganizing a condition in the interface does not invalidate existing project data.

This ticket defines the metadata required for serialization but does not implement PSDK runtime execution.

Localization

• Categories, condition labels, operators, helper texts and validation messages are localizable.
• No user-facing condition label is hardcoded in the registry.
• Translation keys follow Pokémon Studio naming conventions.
• Technical identifiers remain language-independent.

Documentation

• Developer documentation explains the Condition Registry contract.
• Developer documentation explains how to register a new condition.
• Developer documentation explains stable identifier and localization requirements.
• User documentation lists all conditions available in the MVP.
• User documentation explains advanced usage and limitations of Custom Script.

Identified and Relevant Use Cases

RPG Maker XP Migration

• Rebuilding Conditional Branch commands without losing supported behavior.
• Converting Switches into boolean Variables.
• Converting Self Switches into boolean Event Variables.
• Preserving common conditions involving money, items, timers, input and directions.

Common Pokémon Fangame Logic

• Checking whether the player owns a badge.
• Checking the player's badge count.
• Checking whether a Pokémon species is in the party.
• Checking party size.
• Checking the current map.
• Checking the active weather.
• Checking player terrain and system tags.

Advanced Compatibility

• Preserving uncommon or project-specific logic through a Custom Script condition when no dedicated registry definition exists.

Out of Scope

This story does not include:

• the Condition Builder design or UI implementation
• logical group creation using AND or OR
• condition tree serialization performed by the Builder
• PSDK runtime evaluation
• compilation into executable PSDK instructions
• RPG Maker XP migration logic
• plugin-defined condition registration
• String Variable conditions (probably not in 3.0 MVP neither)
• quests
• Pokédex conditions
• followers
• Day Care
• advanced Pokémon properties
• regions, until their PSDK data model is stabilized
• every potential condition listed in future iterations.

Product Notes

The registry should remain intentionally declarative.

It answers questions such as:

• What is this condition called?
• In which category does it appear?
• Which operators can be used?
• Which values must the user provide?
• Which editor should the Builder render?
• How is the condition identified in serialized data?

It should not:

• render the interface itself
• decide how logical groups are displayed
• execute gameplay logic
• generate arbitrary Ruby code
• contain feature-specific UI flows.

The MVP catalog should remain limited to confirmed migration requirements and high-frequency Pokémon fangame needs. Additional conditions should be delivered incrementally through dedicated tickets rather than expanding this story into the complete PSDK condition catalog.