API Reference

The rest of plugin.siren.API.CultivationAPI - the methods an addon calls directly, rather than the events it listens to or the registries it adds to.

Everything on the class is static; the constructor is private and it is never instantiated. Most methods take the same two arguments every Hytale ECS system already has in hand:

• ComponentAccessor<EntityStore> accessor - the accessor for the store the entity lives in.
• Ref<EntityStore> ref - the entity itself.

Threading

The source is explicit about this in one place: the event listeners are invoked synchronously on the world thread of the player the event happened to, and you must hop threads yourself - CompletableFuture.runAsync(task, otherWorld) - before touching anything that lives on another world.

The reads below carry no separate documented threading contract of their own; they are plain component reads through the accessor you pass in, so the accessor's own thread rules apply. Call them from the world thread that owns the Ref you are reading.

Registration and listener calls are the exception in the opposite direction: they are safe from any plugin's setup() in any load order, because the backing structures are static maps and CopyOnWriteArrayLists that nothing reads until a player interacts with the mod.

Component types

Ask for a ComponentType when you want to read or write a Cultivation component through the ECS yourself rather than through the convenience reads below.

Cultivation state

CultivationRealm runs BODY_REFINEMENT, QI_CONDENSATION, FOUNDATION_ESTABLISHMENT, GOLDEN_CORE_FORMATION, NASCENT_SOUL, SOUL_FORMATION, VOID_REFINEMENT. CultivationStage runs EARLY, MIDDLE, LATE, PEAK. Both are documented player-side on the Cultivation Realms page.

There is no setQi or grantQi on the facade. To change a player's banked Qi from an addon, hook CultivationEvents.onPreQiGain and re-scale event.setAmount(...) on the gain that is already happening - that is the supported path, and it is the same one the mod's own race, skill, pill, sect and dao multipliers take. See the events page.

Config files

v0.6.1 Every one of Cultivation's nineteen config files is readable and writable through CultivationConfigs, so an add-on never has to import the mod's internals to ask what this server is running.

// Read
boolean daoOn = CultivationConfigs.dao().get().isDaoEnabled();

// Write - persisting is the caller's job, so a batch of edits costs one file write
var holder = CultivationConfigs.spiritVein();
holder.get().setSpiritVeinRegenPerSecond(2.5f);
holder.save();

Accessors, grouped as the config folders are: cultivation(), spiritCores(), spiritVein(), breakthrough(), skillTree(), raceSystem(), race(PlayerRace) · dao(), technique(), manual(), alchemy(), refinement(), lifeBound(), beast() · sect(), formation(), dwelling(), war(), duel(), partner(), endlessLeveling().

Driving progression

v0.6.1 The write half of the reads above. Every one of these goes through the same path the mod's own commands and rituals use, so an add-on granting Qi fires the same events, honours an installed ProgressionProvider, and refreshes the HUD and rankings exactly as meditating would - none of which is true of reaching into the component.

The world's Qi

v0.6.1 readSpiritVein(World world, int chunkX, int chunkZ) reports what a chunk's Spirit Vein holds without creating or writing anything - and answers truthfully for a chunk nobody has ever visited, because the seeding roll is a pure function of the world seed and the chunk position. That is what makes a map overlay or a divining item possible without seeding a vein into every chunk a player walks past.

drainSpiritVein(World world, int chunkX, int chunkZ, float amount) draws from it, returning how much was actually available. Must run on that world's own thread.

Coordinates are chunk coordinates, not blocks - divide by 16, or use ChunkUtil.chunkCoordinate(blockX).

Asking the subsystems

v0.6.1 The events for sects, daos, beasts, dwellings and duels existed with no way to ask a question - listening to SectEvents without being able to say "what sect is this player in" meant shadowing the whole registry. These close that gap.

Profiles, titles and palettes

v0.7.0 The read surface for a player's saved cultivators and their cosmetics. Note these take a Store<EntityStore> rather than a ComponentAccessor.

Profiles are observed, not driven. There is deliberately no switchProfile on the facade - a switch is the player's own act, through the menu or /cultivation profile. What an addon does is listen (ProfileEvents, see Events), keep its own per-profile state in step, and declare that it does so via ProgressionProvider.supportsProfiles() (see Building Add-ons).

Which mods are installed

v0.6.1 See Compatibility for what each of these changes.

Skill tree

Node ids are the ones in plugin.siren.ECS.SkillTree.SkillTreeRegistry - for example "VITALITY_1". The player-facing map of the tree is on the Skill Tree page, and points are granted per the Points-Per-Breakthrough and Points-Per-Advancement keys on the Config page.

Techniques

This runs every gate - system enabled, per-technique enabled, realm unlock, dao match, Qi cost, cooldown - and on success deducts the Qi, stamps the cooldown and runs the effect. The player is messaged either way, with the effect's success message or the failure reason. Use it to wire a technique to your own trigger: a keybind, a different item, an event of your own.

It works on built-in techniques and on ones you registered yourself, and it fires TechniqueEvents.PreTechniquePerformEvent and TechniquePerformEvent in both cases. See API Registries for building a technique, and Techniques for the player-facing list.

Registration

Covered in full on API Registries:

See also

• API Events - reshape or veto any mechanic.
• API Registries - add races, techniques, Qi items, titles, sect banners and palettes.
• Config and Commands - the server-owner-facing equivalents of most of the above.