> For the complete documentation index, see [llms.txt](https://stellarskills.gitbook.io/stellarskills-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://stellarskills.gitbook.io/stellarskills-docs/configuration/journey.md).

# journey

Journey is a separate data-driven suite in `features.yml`, augmented by `journey_expansions.yml`. It includes specializations, milestones, research, contracts, mastery, social/group systems, saved builds, rankings, and diagnostics. It is **not** identical to the new XP quest journal.

The expansion suite is merged into the base suite. **The base `features.yml` wins for a duplicate module ID as a whole; entries inside the two same-ID modules are not merged individually.** Base suite settings also win. Use distinct module IDs when adding expansion content. Disabling the expansion file is not the same as disabling all modules in `features.yml`.

## Root and module fields

| Root field          | Meaning                                                                                        |
| ------------------- | ---------------------------------------------------------------------------------------------- |
| `enabled`           | Enables that feature suite definition                                                          |
| `title`, `subtitle` | Hub text                                                                                       |
| `theme`             | `inherit` resolves an accessible skill-tree theme; use a supported explicit theme to pin it    |
| `settings`          | Suite controls such as reward commands, leaderboard limit, aura-source limit and rotation seed |
| `modules`           | Map of stable module IDs                                                                       |

| Module field                                            | Meaning                                                    |
| ------------------------------------------------------- | ---------------------------------------------------------- |
| `kind`                                                  | Behavior family; see the generated module reference        |
| `title`, `description`, `icon`, `accent-color`, `order` | Presentation and ordering                                  |
| `enabled`                                               | Hide/disable the module's normal activity                  |
| `maximum-selections`                                    | Selected-entry count ceiling; 0 is not a one-selection cap |
| `selection-groups`                                      | Separate weighted budgets for subsets of entries           |
| `reset`                                                 | `never`, `daily`, `weekly`, `monthly`, `seasonal`          |
| `settings`                                              | Kind-specific switches                                     |
| `entries`                                               | Map of stable entry IDs                                    |

Do not invent a new `kind` and expect new gameplay logic. Use one of the implemented families; utilities such as templates/analytics are not full independent automation engines just because they have cards.

## Common entry fields

Entries accept `title`, `description`, `icon`, `order`, `enabled`, `hidden`, `selectable`, `event`, `target`, `repeat`, `repeat-interval-seconds`, `maximum-completions`, `filters`, `requires`, `conflicts`, `required-classes`, `required-nodes`, `minimum-level`, `maximum-level`, `minimum-prestige`, `reward`, `effects`, and `metadata`.

References in `requires`/`conflicts` can be entry IDs in the same module or `module:entry` references. `required-nodes` uses `tree:node`. For tracking actions, use the server event list and event-specific filters. Selectable/utility entries may leave `event` blank.

## Rewards are different from quest rewards

```yaml
reward:
  experience: 400
  currencies: {skill_points: 2}
  title: Field Researcher
  badge: Ember Journal
  celebration: constellation_burst
  commands: []
```

Journey `reward.experience` pays XP; `currencies` or `currency` plus `amount` pays direct currency. This remains independent of XP-only quests and the legacy direct-source switch. Titles/badges appear in the player profile. A configured celebration ID is descriptive data consumed by the available client behavior, not a way to add a new renderer.

{% hint style="warning" %}
Reward commands are ignored unless suite `settings.allow-reward-commands: true`. When enabled, they run with elevated command authority and replace `{player}`, `{uuid}`, `{module}`, `{entry}`, `{completions}`. Do not accept command strings from untrusted users or rely on this switch to control the separate permission-effect provider commands.
{% endhint %}

Progress/reward calls use idempotent identifiers, but not every compound Journey workflow shares one all-or-nothing database transaction. For critical rewards, keep values conservative, test failure recovery, and inspect audits.

## Selection budgets and sub-branches

```yaml
maximum-selections: 3
selection-groups:
  career_path:
    title: Career Path
    maximum-points: 2
entries:
  rare_hunter:
    title: Rare Hunter
    selectable: true
    selection-group: career_path
    selection-points: 2
  field_assistant:
    title: Field Assistant
    selectable: true
    selection-group: career_path
    selection-points: 1
```

This fragment illustrates a module: the total selected count is at most three, while entries in `career_path` may spend at most two selection points. A two-point Rare Hunter consumes the whole group budget. Use additional groups for independent choices. Groups currently have a maximum budget, not a configurable minimum quota.

These budgets apply to Journey selections, not purchased skill ranks. Use node subclass groups for mutually exclusive skill-tree branches and effect choice counts for alternatives within a node.

## High-value module recipes

| Family                                   | Configuration focus                                                                                                 |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| Specialization                           | `selectable`, required class/level, conflicts, weighted selection groups                                            |
| Prestige                                 | `settings.required-level`, `reset-level`, `reset-trees`, `refund-trees`; review destructive effects before enabling |
| Contract                                 | Event/target/filter, rotation count/period, reset window and reward                                                 |
| Partner mastery                          | Bind a supported party partner; rules depend on its Pokemon UUID                                                    |
| Type/research/breeding/evolution mastery | Event-based persistent progress and readable filters                                                                |
| Discovery                                | `metadata.discover-nodes` with `tree:node` IDs                                                                      |
| Synergy/socket/transformation            | Eligibility and supported entry effects; not arbitrary component replacement                                        |
| Aura                                     | Radius, allowed selections, suite source cap; test nearby recipient behavior                                        |
| Node trial                               | `metadata.tree`, `node`, `required-rank` plus an event target before that rank can be purchased                     |
| Team resonance                           | Party size/types/species/health constraints; dynamically enables/disables supported effects                         |
| Convergence                              | Required classes plus a target tree; useful only when multi-class selection is achievable                           |
| Campaign                                 | Selectable branch entries and prerequisites; separate from XP quests                                                |
| Season                                   | `starts-at`, `ends-at`, `season-id`, progress/catch-up multipliers                                                  |
| Community project                        | Shared target, `metadata.minimum-contribution`, completion broadcast, contributor claims                            |
| Field attunement                         | Dimension/biome/weather/time/moon/altitude/spawn-distance gates                                                     |
| Oath/streak                              | Voluntary active challenge and explicit `break-events`                                                              |
| Build advisor                            | Read-only scoring via class/type/species recommendation metadata                                                    |
| Mastery codex                            | Permanent species/type milestones                                                                                   |
| Loadout/build sharing                    | Saved rank/choice builds, guarded apply, safe-area/cost/cooldown rules                                              |
| Objective tracker                        | Local pinned-entry display; separate from the disabled RPG HUD                                                      |
| Balance dashboard                        | Read-only admin diagnostics, not a universal economy report                                                         |

## Dynamic constraints

Team/environment metadata supports `minimum-party-size`, `maximum-party-size`, `minimum-unique-types`, `maximum-legendary`, `required-types`, `excluded-types`, `required-species`, `excluded-species`, `monotype`, `unique-species`, `all-healthy`, `same-generation`, `minimum-average-level`, `dimensions`, `biomes`, `weather`, `time`, `moon-phases`, `minimum-y`, `maximum-y`, and `maximum-spawn-distance` where the family evaluates them.

Use comma-separated values in scalar metadata, such as `required-types: 'fire,water,grass'`. Metadata normalization converts hyphens to underscores internally. Arbitrary metadata only becomes a rule when that family consumes it.

Season scheduling accepts UTC dates or ISO-8601 instants. `ends-at` closes eligibility; reset history follows the configured reset/window/season ID. Oath breaks must be events the server actually emits (`player_damaged`, `player_death`, `heal_team`, `battle_lost`, etc.), not invented client reports.

## Loadout safety

Packaged loadouts default to `allow-apply: false`, `safe-area-only: true`, spawn-distance restrictions, a cooldown, and optional currency cost. A saved build is not authority: apply validates class access, nodes, ranks, effects choices and constraints again. Invalid legacy builds that omit choices for a newly choice-enabled node are rejected rather than silently selecting an option.

Applying a build is an explicit state-changing workflow. Do not treat its export string as a full server/player backup, or assume every multi-tree apply has one globally atomic transaction.

Full defaults and all module/entry IDs are in [Journey reference](file:///4985688/reference/journey-modules.md), [features.yml](file:///4985688/reference/features.md), and [journey\_expansions.yml](file:///4985688/reference/journey-expansions.md).