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 LegacyPowerTypeAliases.java, which translates neoorigins: / apace: / apoli: / apugli: types into the 2.0 vocabulary at load time. See MIGRATION.md.

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 — 10 common patterns.
PACK_FORMAT.md Directory layout, file-name conventions, JSON boilerplate.
ARCHITECTURE.md How powers are loaded, dispatched, cached. For debugging.
2_0_CHANGES.md Phase-by-phase log of the 2.0 consolidation.

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 field on a power file selects one of these. All use the neoorigins: namespace; see Namespaces for how legacy prefixes map.

Each row jumps to its section in POWER_TYPES.md.

Generic composable (use these for new powers)

Type Summary
action_on_event Run an action (or modify a float) when an event fires. Workhorse event-listener.
action_on_hit Run an action when the player deals damage. Filterable by target.
active_ability Skill-key-triggered ability running one or more actions. Cooldown + hunger cost.
attribute_modifier Add/multiply a player attribute. Optional tick-driven condition gate.
condition_passive Run an action on an interval while a condition holds. Workhorse passive.
conditional Gate another power on a static condition enum.
edible_item Make arbitrary items edible for this player.
modify_damage Scale damage the player deals or takes. Direction + type/tag filter.
persistent_effect Refresh a status effect every tick. Replaces legacy status_effect.
prevent_action Cancel a specific player action (FALL_DAMAGE, DROWN, FIRE, SWIM, etc.).
toggle Boolean state cycled by the skill key, readable via neoorigins:power_active.

Movement & body

Type Summary
elytra_boost Add forward thrust while elytra-flying.
enhanced_vision Permanent brightness floor. Replaces legacy night_vision.
flight Creative-style flight.
phantom_form Mayfly + noPhysics + no-fall — walk through walls.
size_scaling Scale player dimensions. Optional reach-scaling.
wall_climbing Scale walls like a spider.
water_breathing Never loses air underwater.
cobweb_affinity Web mobility + 10× cobweb break speed.
burn Set the player on fire at a configurable interval.
ignore_water Full land speed in water + no current pushing.
lava_vision Increase vision distance in lava.
overlay Full-screen texture overlay with configurable opacity.
model_color RGBA tint on the player model.
shader Post-processing shader on the player’s view.

Minions & entities

Type Summary
summon_minion Active ability that spawns a tracked mob with owner-aware AI.
tame_mob Active ability that rewrites a mob’s AI to follow and defend the owner.
tamed_animal_boost Buff vanilla tamed animals (HP / speed).
tamed_potion_diffusal Potions drunk near tamed animals apply to them too.
entity_group Mark the player as part of an entity group (undead, arthropod). Affects effect applicability + enchantment bonuses.
entity_set Named UUID set per power id. Pair with neoorigins:in_set / add_to_set / remove_from_set.
mobs_ignore_player Mobs don’t aggro. Retaliation window preserved.
scare_entities Listed entity types flee from the player.
no_mob_spawns_nearby Cancel natural spawns in a radius.
twin_breeding Chance for breeding to yield two babies.

Combat

Type Summary
invulnerability Filter damage types the player is immune to.
projectile_immunity Filter projectile types the player is immune to.
effect_immunity Block specific status effects.
dodge_chance Percentage chance to dodge incoming damage.
thorns_on_hit Passive thorns — attacker takes damage back.
light_level_effect Apply effect at/below a light level.
low_hp_threshold Apply effects when HP drops below a threshold.
ender_gaze_immunity Endermen don’t aggro on eye contact.
ground_slam Radial AoE damage from falling.
tidal_wave Active cone-shape knockback.
shadow_orb Place a stationary orb emitting Darkness + Blindness.

Mining, farming, crafting

Type Summary
break_speed_modifier Multiply block break speed with block/tool/condition filters.
underwater_mining_speed Remove underwater mining penalty.
tree_felling Chop connected logs in one swing.
crop_growth_accelerator Periodic tick boost to nearby crops.
crop_harvest_bonus +N drops per crop break.
quality_equipment Starting tool quality uplift.
craft_amount_bonus Extra output on crafted items.
more_smoker_xp Bonus XP from smoker.

Inventory & items

Type Summary
starting_equipment Grant items on origin chosen.
keep_inventory Slot/item filter for inventory kept across death.
restrict_armor Slot-scoped gate on wearable items.
item_magnetism Pull item entities to the player.
hide_hud_bar Hide the food or air bar.

Healing, hunger, survival

Type Summary
horde_regen Regen scales with nearby allied mob count.
no_natural_regen Kill food-driven regen; potion/beacon heals still work.
exhaustion_filter Selective hunger-drain modifier.
no_slowdown Immune to specific slowdown sources.
breath_in_fluid Air supply drains in named fluids.

Respawn & lifecycle

Type Summary
modify_player_spawn Per-power respawn override. Optional bed override.

Merchant & loot

Type Summary
trade_availability Extend villager trade offers.
rare_wandering_loot Bonus wandering-trader drops.

Command integration

Type Summary
command_pack Package of execute_command actions behind a single power id.

Active abilities (specialised)

Type Summary
active_bolt Fires a wind-charge projectile. Legacy; prefer active_ability + spawn_projectile.
active_dash Horizontal impulse. Legacy; see MIGRATION.md.
active_fireball Single small fireball. Legacy.
active_phase Toggle movement state. Legacy.
active_place_block Raycast and place. Legacy; no DSL verb yet.
active_recall Saved-position teleport. Legacy; stateful.
active_swap Swap positions with target.
active_teleport Look-direction blink. Legacy; no DSL verb yet.

Deprecated & retired

Retired concrete types that still load via alias. See MIGRATION.md for the remap table.

Type Replaced by
less_item_use_slowdown attribute_modifier + neoorigins:using_item condition
no_projectile_divergence attribute_modifier on minecraft:projectile_accuracy
sneaky / stealth mobs_ignore_player + sneak gate
tick_action action_on_event with event: tick

Condition verbs

Used in condition fields. All use the neoorigins: namespace (the apace: namespace is also accepted; they’re aliases). Jumps go to CONDITIONS.md.

Boolean combinators

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

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

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

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

Power introspection

neoorigins:power_active • neoorigins:power_type • neoorigins:in_set

Advanced

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

Action verbs

Used in entity_action fields. All use the neoorigins: namespace (the apace: namespace is also accepted). Jumps go to ACTIONS.md.

Combinators & control

neoorigins:and • neoorigins:chance • neoorigins:delay • neoorigins:if_else • neoorigins:if_else_list • neoorigins:nothing

Damage & healing

neoorigins:damage • neoorigins:heal • neoorigins:feed • neoorigins:exhaust • neoorigins:change_resource

Effects

neoorigins:apply_effect • neoorigins:clear_effect

Movement & position

neoorigins:add_velocity • neoorigins:launch • neoorigins:set_fall_distance • neoorigins:dismount • neoorigins:throw_target

Items & inventory

neoorigins:give • neoorigins:modify_food • neoorigins:spawn_entity • neoorigins:spawn_projectile

World & environment

neoorigins:set_block • neoorigins:set_on_fire • neoorigins:extinguish • neoorigins:explode • neoorigins:gain_air • neoorigins:area_of_effect

Power control

neoorigins:grant_power • neoorigins:revoke_power • neoorigins:trigger_cooldown

Integration

neoorigins:execute_command • neoorigins:play_sound • neoorigins:swing_hand • neoorigins:emit_game_event

Event keys

Used in action_on_event’s event field. Case-insensitive.

Core lifecycle & combat

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

Interactions

BONEMEAL • FOOD_EATEN • BLOCK_USE • ENTITY_USE • ITEM_PICKUP • ITEM_USE_FINISH

Origin & power lifecycle

GAINED • LOST • CHOSEN • WAKE_UP • LAND

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

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

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.
neoorigins:* Upstream Apoli / vanilla Origins. Translator in OriginsCompatPowerLoader maps to neoorigins:* or a DSL recipe.
apace:* Apace mod variant. Same translator as neoorigins:*.
apoli:* Upstream Apoli mod. LegacyPowerTypeAliases remaps to 2.0 generics.
apugli:* Apugli mod. LegacyPowerTypeAliases remaps; Tier-1 aliases only (edible_item, action_on_jump, action_on_target_death).

Running on a mixed pack: if two prefixes point at the same conceptual power and the fields differ, the alias remap picks the intersection of supported fields. Extra fields from the legacy type are dropped with a one-time [2.0-legacy] log warning.

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/

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.

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/ConditionParser.java
  • Action verbs: src/main/java/com/cyberday1/neoorigins/compat/action/ActionParser.java
  • Event keys: src/main/java/com/cyberday1/neoorigins/service/EventPowerIndex.java
  • Legacy aliases: src/main/java/com/cyberday1/neoorigins/power/registry/LegacyPowerTypeAliases.java