# Overview

`PassiveSTJS` exposes Passive Skill Tree through four script surfaces:

1. `StartupEvents.registry('skilltree:...')` for serializer-backed custom types.
2. `PassiveSTJSEvents.skillTreeContent(...)` for managed tree and skill content generation.
3. `PassiveSkillTreeJS` bindings for runtime inspection and mutation.
4. `event.recipes.skilltree.workbench_item_bonus()` for PST workbench socket recipes.

## Script Locations

Use each surface in the correct KubeJS folder:

- `kubejs/startup_scripts/`
  For `StartupEvents.registry('skilltree:...')`.
- `kubejs/server_scripts/`
  For `PassiveSTJSEvents.skillTreeContent(...)`, runtime helper usage, and recipe registration.
- `kubejs/client_scripts/`
  For `ClientEvents.lang(...)` entries that provide titles, descriptions, tooltip fragments, and workbench text.

## Main Entry Points

The public event and binding entry points are:

- `PassiveSTJSEvents.skillTreeContent(event => { ... })`
- `PassiveSkillTreeJS.player(player)`
- `PassiveSkillTreeJS.skill(id)`
- `PassiveSkillTreeJS.tree(id)`
- `PassiveSkillTreeJS.item(stack)`

The content event writes generated JSON into KubeJS' virtual datapack and then applies it to PST runtime caches after the event posts.

## Startup Registry Families

`PassiveSTJS` installs `StartupEvents.registry(...)` support for these PST serializer families:

- `skilltree:skill_bonuses`
- `skilltree:skill_bonus_multipliers`
- `skilltree:living_conditions`
- `skilltree:damage_conditions`
- `skilltree:item_conditions`
- `skilltree:enchantment_conditions`
- `skilltree:event_listeners`
- `skilltree:numeric_value_providers`
- `skilltree:skill_requirements`
- `skilltree:item_bonuses`

Inside `skillTreeContent`, `event.registries()` exposes the real PST registry view for the same families.

## Typed Authoring

The addon ships typed ids and enums for the common PST paths used in scripts and recipes. The checked-in examples show this style directly:

- typed tree and skill ids
- typed registry ids for bonuses, listeners, requirements, conditions, and item bonuses
- typed equipment types, textures, frame types, logic enums, effect ids, attribute ids, item ids, tag ids, and potion ids

This is the intended authoring path when Probe or generated typings are available.

## Docs Map

- [Startup Registry Integration](./startupevents/registry)
  How custom serializer-backed PST types are registered.
- [Server Content Event](./serverevents/content)
  How trees and skills are added, edited, removed, or replaced.
- [Runtime Helpers](./runtime-helpers)
  How player, tree, skill, and item helpers are used at runtime.
- [Workbench Recipes](./recipes)
  How `skilltree:workbench_item_bonus` is authored through RecipeJS.
- [Config](./config)
  What `passivestjs-common.toml` controls.
- [Examples](./examples)
  Which checked-in sample file demonstrates which API surface.

## Version Notes

- Minecraft: `1.20.1`
- Forge: `47.4.18`
- KubeJS: `2001.6.5-build.22`
- Shared config: `config/passivestjs-common.toml`