NeoOrigins 2.0 API Reference

Single landing page for the NeoOrigins datapack API. Every power type, condition verb, action verb, and event key is listed below with a jump-link to the per-topic detail doc.

Layer model

A NeoOrigins pack is composed of four layers, each authored in JSON:

  1. Origin layers (origins/origin_layers/*.json) control which origins show in the picker. Override neoorigins:origin to add your origins to the main picker tab.
  2. Origins (origins/origins/*.json) define each selectable origin: name, description, icon, impact, and the list of powers it grants.
  3. Powers (origins/powers/*.json) are the mechanical units. Each has a type (see the power-type index below) plus the type-specific fields.
  4. Composition DSL: most 2.0 power types accept a condition (a predicate on the player) and either an entity_action (a side-effect) or an event key. Conditions and actions are themselves JSON objects with their own type and fields; they can be nested (neoorigins:and, neoorigins:not, neoorigins:or) to express arbitrary logic.

A tick-driven gate like “take damage in the Nether, unless wearing Frost Walker boots” is expressed as one power whose condition is an neoorigins:and of neoorigins:biome and neoorigins:not(origins:enchantment). The 2.0 design goal is that virtually any behaviour a pack wants is a composition of verbs that already exist, rather than a bespoke power type.

The upstream layer (for cross-mod pack compatibility) is handled by the compat loader: origins: and apace: types are translated into the 2.0 vocabulary by OriginsPowerTranslator / OriginsCompatPowerLoader, while apoli: and apugli: spellings are canonicalized to origins: first. LegacyPowerTypeAliases is a narrower remap table: retired neoorigins: ids plus a few cross-mod entries. See MIGRATION.md and the Namespaces table.

Documents in this API

Doc What it covers
POWER_TYPES.md Full field table for every power type. Source of truth for allowable fields.
CONDITIONS.md Every condition verb with fields and semantics.
ACTIONS.md Every action verb with fields and semantics.
EVENTS.md Every event key the action_on_event power can listen on.
MIGRATION.md Legacy type → 2.0 type remap table, lossy translations, DSL gap catalog.
COOKBOOK.md Recipe-oriented tutorial: a five-minute starter origin, then worked recipes for common patterns.
PACK_FORMAT.md Directory layout, file-name conventions, JSON boilerplate.
CONTENT_CONFIG.md Server content.toml toggles: global vision / resource-bar switches and per-origin / per-class enable flags.
CLIENT_CONFIG.md Per-client client.toml options: UI theme, HUD layout, hotkey pool size.
GAMEPLAY_CONFIG.md gameplay.toml options: Orb of Origins costs, random assignment, evolution kill counts, ocean-origin survival, sun damage, mount consent, friendly fire, armor classes.
ADMIN_CONFIG.md admin.toml policy: command-power blacklist, dimension restrictions, compat origin filtering, taming exclusions, debug flags.
ARCHITECTURE.md How powers are loaded, dispatched, cached. For debugging.
COMPATIBILITY.md Out-of-the-box mod integrations (Origins/Apoli, Curios, Ars Nouveau, KubeJS, JEI/REI, etc.).

If a prose doc disagrees with the code, the code wins. Source of truth paths are cross-linked in each detail doc.

Power types

The type index, grouped by category with a one-line summary per type, is on Power Types. Each category has its own page under powers/.

1.21.1 vs 26.x: model_color draws nothing on 26.x; js_active and js_custom are registered on 1.21.1 and 26.1 only; ultimine is an inert marker on 26.2 and 26.3.

Condition verbs

Used in condition fields. A bare verb name defaults to neoorigins:; any other namespace (origins:, apace:, apoli:, apugli:, …) is rewritten to neoorigins: with a one-time [2.0-legacy] warning. An unknown verb fails closed. Each entry jumps to CONDITIONS.md.

Alias spellings (dispatch to the same verb, not counted above): riding → passenger, fire → on_fire, food → food_level, name → damage_name, replaceable → replacable, resource_level → resource, covered_by_block → cover, block_in_radius → near_block, all_of → and, any_of → or.

Boolean combinators

neoorigins:and • neoorigins:or • neoorigins:not • neoorigins:constant • neoorigins:always_active

Environment

neoorigins:biome • neoorigins:dimension • neoorigins:in_tag • neoorigins:submerged_in • neoorigins:submerged_in_water • neoorigins:in_water • neoorigins:in_block • neoorigins:on_block • neoorigins:block • neoorigins:block_collision • neoorigins:on_ground • neoorigins:on_fire • neoorigins:in_rain • neoorigins:temperature • neoorigins:weather • neoorigins:brightness • neoorigins:light_level • neoorigins:exposed_to_sky • neoorigins:exposed_to_sun • neoorigins:daytime • neoorigins:time_of_day • neoorigins:moon_phase • neoorigins:height • neoorigins:fluid_height • neoorigins:distance • neoorigins:near_entity • neoorigins:nearby_entities • neoorigins:near_villager • neoorigins:near_block • neoorigins:in_block_anywhere • neoorigins:distance_from_coordinates • neoorigins:cover • neoorigins:hardness • neoorigins:replacable • neoorigins:night • neoorigins:thundering

Player state

neoorigins:health • neoorigins:relative_health • neoorigins:food_level • neoorigins:armor_value • neoorigins:xp_level • neoorigins:xp_points • neoorigins:fall_distance • neoorigins:fall_flying • neoorigins:sneaking • neoorigins:sprinting • neoorigins:swimming • neoorigins:invisible • neoorigins:creative_flying • neoorigins:moving • neoorigins:passenger • neoorigins:using_item • neoorigins:equipped_item • neoorigins:enchantment • neoorigins:resource • neoorigins:living • neoorigins:exists • neoorigins:ticking • neoorigins:advancement • neoorigins:air • neoorigins:body_temperature • neoorigins:climbing • neoorigins:climbing_gate • neoorigins:collided_horizontally • neoorigins:creative_mode • neoorigins:has_effect • neoorigins:status_effect • neoorigins:inventory • neoorigins:saturation_level • neoorigins:using_effective_tool • neoorigins:xp_levels

Food context

neoorigins:food_item_id • neoorigins:food_item_in_tag • neoorigins:food_item_in_config_list

Entity & damage

neoorigins:entity_type • neoorigins:target_type • neoorigins:target_group • neoorigins:can_see • neoorigins:damage_type • neoorigins:damage_tag • neoorigins:damage_name • neoorigins:from_fire • neoorigins:from_projectile • neoorigins:from_explosion • neoorigins:actor_condition • neoorigins:hit_dealt_amount • neoorigins:hit_taken_amount • neoorigins:out_of_combat

Power introspection

neoorigins:power_active • neoorigins:power_type • neoorigins:in_set • neoorigins:power • neoorigins:origin • neoorigins:cooldown • neoorigins:no_minions_alive

Advanced

neoorigins:nbt • neoorigins:scoreboard • neoorigins:statistic • neoorigins:command • neoorigins:predicate • neoorigins:amount • neoorigins:equal • neoorigins:config_flag

Action verbs

Used in entity_action fields. Namespace handling is the same as for conditions (bare name → neoorigins:; other namespaces rewritten with a one-time warning). Each entry jumps to ACTIONS.md.

Two caveats. In a bientity action slot, pair behaviour (actor/target wrappers, and, chance, invert, damage, mount, if_else) only exists for the literal origins: / apoli: / apace: spellings; any other type, including a neoorigins: one, is parsed as a plain entity action and runs on the actor, with the target published as context. And the entity-action neoorigins:invert is registered but is a no-op (it parses to EntityAction.noop()); only the bientity origins:invert swaps actor and target.

Alias spellings (dispatch to the same verb, not counted above): all_of → and, bonemeal → grow, modify_resource → change_resource, fire_projectile → spawn_projectile, command → execute_command, spawn_sword_rain → spawn_projectile_rain.

Combinators & control

neoorigins:and • neoorigins:chance • neoorigins:delay • neoorigins:if_else • neoorigins:if_else_list • neoorigins:nothing • neoorigins:choice • neoorigins:invert (no-op; see above) • neoorigins:cancel_event

Wrappers & targeting

neoorigins:actor_action • neoorigins:target_action • neoorigins:riding_action • neoorigins:passenger_action • neoorigins:equipped_item_action • neoorigins:block_action_at • neoorigins:block_target_action • neoorigins:selector_action • neoorigins:raycast • neoorigins:offset

Damage & healing

neoorigins:damage • neoorigins:heal • neoorigins:feed • neoorigins:exhaust • neoorigins:change_resource • neoorigins:damage_attacker • neoorigins:ignite_attacker • neoorigins:effect_on_attacker

Effects

neoorigins:apply_effect • neoorigins:clear_effect • neoorigins:spawn_effect_cloud • neoorigins:spawn_lingering_area • neoorigins:modify_temperature

Movement & position

neoorigins:add_velocity • neoorigins:launch • neoorigins:set_fall_distance • neoorigins:dismount • neoorigins:throw_target • neoorigins:dash • neoorigins:mount • neoorigins:random_teleport • neoorigins:swap_positions • neoorigins:swap_with_entity • neoorigins:teleport_target_to_self • neoorigins:teleport_to_marker • neoorigins:teleport_to_target

Items & inventory

neoorigins:give • neoorigins:modify_food • neoorigins:spawn_entity • neoorigins:spawn_projectile • neoorigins:drop_inventory • neoorigins:drop_items • neoorigins:force_drop • neoorigins:steal_item • neoorigins:modify_inventory • neoorigins:dye • neoorigins:shear • neoorigins:add_xp • neoorigins:crafting_table

World & environment

neoorigins:set_block • neoorigins:set_on_fire • neoorigins:extinguish • neoorigins:explode • neoorigins:gain_air • neoorigins:area_of_effect • neoorigins:grow • neoorigins:till • neoorigins:path • neoorigins:strip • neoorigins:transform_block • neoorigins:spawn_black_hole • neoorigins:spawn_tornado • neoorigins:spawn_projectile_rain • neoorigins:spawn_telegraph • neoorigins:spawn_particles

Power control

neoorigins:grant_power • neoorigins:revoke_power • neoorigins:trigger_cooldown • neoorigins:activate_power • neoorigins:toggle • neoorigins:set_resource • neoorigins:open_layer_picker

Entities & sets

neoorigins:tame_target • neoorigins:chain_to_nearest • neoorigins:pull_entities • neoorigins:add_to_set • neoorigins:remove_from_set • neoorigins:morph_entity_event • neoorigins:trigger_morph_animation

Integration

neoorigins:execute_command • neoorigins:play_sound • neoorigins:swing_hand • neoorigins:emit_game_event • neoorigins:kubejs_callback • neoorigins:cast_spell • neoorigins:cast_iron_spell

Event keys

Used in action_on_event’s event field. Case-insensitive. The compat spelling item_use_start also resolves (to ITEM_USE); see EVENTS.md. Each entry jumps to its section in EVENTS.md.

Core lifecycle & combat

ATTACK • HIT_TAKEN • HIT_DEALT • KILL • DEATH • BLOCK_BREAK • BLOCK_PLACE • ITEM_USE • RESPAWN • TICK • DIMENSION_CHANGE • JUMP • CLIMB • PROJECTILE_HIT • EFFECT_APPLIED

Interactions

BONEMEAL • FOOD_EATEN • FOOD_FINISHED • BLOCK_USE • ENTITY_USE • ITEM_PICKUP • ITEM_USE_FINISH • VILLAGER_INTERACT • TRADE_COMPLETED • BREED • TAME • CRAFT_ITEM • SMELT_ITEM • ENCHANT_ITEM • ANVIL_REPAIR • ADVANCEMENT_EARNED

Origin & power lifecycle

GAINED • LOST • CHOSEN • WAKE_UP • LAND • POWER_ACTIVATED

Modifiers (return a float, chain in registration order)

MOD_EXHAUSTION • MOD_NATURAL_REGEN • MOD_ENCHANT_LEVEL • MOD_HARVEST_DROPS • MOD_TELEPORT_RANGE • MOD_KNOCKBACK • MOD_POTION_DURATION • MOD_ANVIL_COST • MOD_CRAFTED_FOOD_SATURATION • MOD_BONEMEAL_EXTRA • MOD_FALL_DAMAGE • MOD_TRADE_PRICE • MOD_CRAFT_AMOUNT • MOD_FOOD_NUTRITION

See EVENTS.md for each event’s context record.

Named keybinds

Moved to Keybinds: the skill slots, the named-keybind pool, numbered slots, vanilla input keys, fail_action and disable_hotkey.

Active theme datapack file

The UI theme used by the origin selection / info screens is selectable per world via a datapack file. Drop the following into any pack:

data/<namespace>/neoorigins/active_theme.json

{ "theme": "examplepack:dark_woods" }

The server reads every active_theme.json on world load + each /reload and broadcasts the selection to every client at login. When multiple packs each declare an active_theme.json, the one loaded last wins and a warning is logged listing every contributor. A per-client override lives at config/neoorigins/client.toml ([ui] theme_override = "<ns>:<id>") and beats the datapack file when set to a loaded id.

For the theme JSON schema (assets/<ns>/ui_themes/<id>.json) and the authoring quickstart, see THEMING.md. A copy-and-edit pack skeleton lives at docs/theme-template/.

Namespaces & prefixes

NeoOrigins accepts legacy prefixes for cross-mod pack compat.

Prefix Meaning How it’s resolved
neoorigins:* Canonical 2.0 namespace. Use this for new packs. Direct registry lookup.
origins:* Upstream Apoli / vanilla Origins. Translator in OriginsCompatPowerLoader maps to neoorigins:* or a DSL recipe.
apace:* Apace mod variant. Same translator as origins:*.
apoli:* Upstream Apoli mod. Canonicalized to origins:* and fed through the same translator; LegacyPowerTypeAliases covers only the odd cross-mod id (e.g. apoli:edible_item).
apugli:* Apugli mod. Canonicalized to origins:* like apoli:* and fed through the same translator. LegacyPowerTypeAliases also covers apugli:edible_item, apugli:action_on_jump and apugli:action_on_target_death.

A remapped type logs one [2.0-legacy] warning per old type id per boot, naming the replacement. The remap rewrites only the fields it knows about; the replacement type’s parser then reads the result, so a field neither the remap nor the new type reads has no effect.

JSON schemas

Machine-readable schemas live under schema/. Point your IDE / datapack validator at:

  • schema/power.schema.json: for files under data/*/origins/powers/
  • schema/origin.schema.json: for files under data/*/origins/origins/
  • schema/origin_layer.schema.json: for files under data/*/origins/origin_layers/
  • schema/mob_origin.schema.json: for files under data/*/origins/mob_origins/
  • schema/morph.schema.json: for files under data/*/neoorigins/morphs/
  • schema/condition.schema.json, schema/action.schema.json, schema/block_condition.schema.json, schema/item_condition.schema.json, schema/item_action.schema.json: the nested condition / action objects

Schemas are derived from the Java Config records and are authoritative against what the loader accepts. If the schema disagrees with a prose doc, the schema wins.

Capability system

Powers declare capability tags via capabilities(Config). These tags are synced to the client and used by client-predicted mixins (e.g. "wall_climb", "wall_phase", "no_physics", "flight").

A player-aware variant capabilities(ServerPlayer, Config) is available for capabilities that depend on runtime state (conditions, resource levels, etc.). Default delegates to the static variant. Used by model_color to conditionally emit the color capability based on a condition field.

Mod integration (Java)

For other mods that need to read or change a player’s origins programmatically.

Where origins live. A player’s per-layer selection is stored on the neoorigins:origin_data data attachment (PlayerOriginData, accessed via player.getData(OriginAttachments.originData())). It persists only the layer → origin map plus a little bookkeeping; a player’s powers are not stored. The active power set is derived at runtime from each assigned origin’s definition (ActiveOriginService), so writing the attachment NBT directly does not apply or remove any powers.

Changing origins cleanly. Because powers are derived, swapping an origin requires running the revoke/grant lifecycle (onRevoked / onGranted, attribute-modifier cleanup, event-handler teardown, client sync). Use the public facade:

  • NeoOriginsAPI.setOrigin(player, layerId, originId) transitions a single layer the way /origin set does, and NeoOriginsAPI.clearOrigin(player, layerId) empties one. See Changing a player’s origin.
  • reapplyOrigins(player, Map<layerId, originId>) on the internal com.cyberday1.neoorigins.service.ActiveOriginService replaces a player’s entire origin selection in one clean call: tears down all current powers, overwrites the layer map, regrants, restores server-global powers, and syncs the client. Intended for profile / loadout mods (e.g. Switchy) that restore a saved origin set. Call this instead of writing the attachment NBT directly to avoid leftover powers from the previous profile. An empty map clears the player to no origins.

Both run the full lifecycle, so the client HUD, keybinds, and attribute state stay consistent. After either call you do not need a separate sync.

Source-of-truth paths

When docs drift, these are the code files that won:

  • Power registrations: src/main/java/com/cyberday1/neoorigins/power/registry/PowerTypes.java
  • Power Config records: src/main/java/com/cyberday1/neoorigins/power/builtin/*.java
  • Condition verbs: src/main/java/com/cyberday1/neoorigins/compat/condition/BuiltinConditions.java (registered descriptors; ConditionParser.java dispatches to them)
  • Action verbs: src/main/java/com/cyberday1/neoorigins/compat/action/BuiltinActions.java (registered descriptors; ActionParser.java dispatches to them)
  • Event keys: src/main/java/com/cyberday1/neoorigins/service/EventPowerIndex.java
  • Legacy aliases: src/main/java/com/cyberday1/neoorigins/power/registry/LegacyPowerTypeAliases.java

Moved from this page

These sections now live on other pages.