Quest Objectives

An objective turns a qualifying server event into numeric progress or a completion flag. Its own type checks run before its event-filter tree; all objectives in the quest must finish before rewards run. Bounty quests additionally require a confirmed receptionist report; see Bounty data.

Where the files live

Objectives are entries in objectives inside data/<namespace>/quests/**/*.json, not separate resources. Quest Data covers the enclosing file, resource priority, identity and atomic catalogue validation. Every built-in objective type below uses the isekaiexpansion namespace.

Minimal example

Insert this entry into a quest’s objectives array alongside the required root fields from Quest Data. It uses the visit-location shape from the demonstration fixtures and needs no type-specific fields. With no event filter, the first qualifying player tick completes it.

{
  "id": "visit",
  "progress_type": "boolean",
  "type": "isekaiexpansion:visit_location",
  "data": {}
}

Fields

Objective envelope

Numeric progress adds a non-negative type-specific increment and saturates at 2147483647. Boolean progress becomes true on the first matching event, independently of that type’s numeric increment. Completed objectives stop receiving normal progress, manual content and failure checks. The ordinary tracker requires a credited player for progress; a nearby uncredited death does not grant kill progress.

Type payloads

These fields are inside the objective’s data. Fields belonging to another type generally do nothing unless a parser explicitly rejects them.

Kill credit resolves direct players, player-owned projectiles and following NPCs, including their projectiles, to a responsible player. party accepts that credited actor for the shared profile; it does not award every nearby team. player excludes companion credit, while picker compares the responsible player with the saved picker. Weapon predicates inspect that player’s hands at event time, not a saved weapon on a projectile or companion.

Interaction callbacks report use attempts and return control to normal interaction handling; the objective does not wait for the block/entity interaction to succeed. Hand/credit option names are trimmed and case-insensitive; unknown names reject the definition. Recipe and advancement objectives react to events after activation, not a scan of historical crafts or already-held advancements.

Entity, item and block predicates

Singular and plural selector keys merge. Both accept a string or array, trim values, ignore blanks and collapse duplicates. Entity-type, item, block and damage tag IDs here are bare IDs without a leading #; location tags below are the exception.

Entity identity accepts a matching type ID or type tag, then requires every command tag and any NBT filter. An empty entity predicate still needs a present, unremoved entity when used as a target. An empty item/block predicate rejects at load. Unknown tag membership normally yields no match; unlike explicit item/block/entity IDs, these tag references are not checked for existence by the predicate parser.

NBT filters compare against entity data, the stack’s own NBT or block-entity data respectively. They are JSON objects using the typed-NBT rules below, not SNBT strings.

Locations and NPC identity

A general location predicate applies dimension, spherical coordinates, biome and structure groups together. Alternatives within the biome group or within the structure group use OR. An empty location object still needs a world and event position.

Location singular/plural selectors merge, trim and ignore blanks like the other predicates. Structure matching uses the containing structure resolved through Isekai Core; a failed lookup means no structure match. NPC selectors test the NPC’s position, whereas an objective location condition tests the event position: the interacted block centre, NPC position, kill position or photo frame position, as appropriate.

NPC identity aliases can match multiple instances of a generic NPC type. Add location bounds when the quest should bind to a particular area. This selector does not enforce unique identity registration.

Delivery

The following fields are inside data.delivery. Enum strings trim and ignore case; unknown options reject the definition.

The main-hand source needs the whole batch in that stack. Inventory and cart sources can aggregate matching stacks within one inventory. Cart selection requires the optional Nifty Carts mod at load time, searches around the NPC and chooses the nearest eligible inventory cart; it does not require that cart to be attached to the carrier.

Automatic proximity checks run every 5 ticks (0.25 seconds at 20 ticks per second), staggered by player entity ID. A pass handles the first successful eligible delivery, not every pending batch. The bridge checks the objective’s event conditions before consumption, then sends a trigger targeted to that quest and objective.

Item count and objective progress are different. A batch of 16 items adds 1 numeric progress; required: 3 therefore needs 3 successful batches. With consume_on_complete: false, a proximity objective can reuse the same held batch on later checks. Delivery consumption and subsequent tracker execution are not a rollback transaction.

The removed delivery.constraints field is explicitly rejected. Put supported failure rules in data.failures.

Objective event conditions

This tree lives at objectives[].conditions. It filters events using location, entity or payload leaves; player-level/team/sequence leaves belong to the separate general condition tree used by picking and content triggers.

Groups short-circuit. A location leaf receives its location fields directly in data; there is no extra location wrapper. An entity leaf also receives entity-predicate fields directly. Missing/removed entities pass only when presence is not required. Payload comparisons use the stored value’s boolean/numeric conversion; there is no strict payload-type validation, so choose a key with the type produced by that event.

Useful non-photo payload keys are hand and sneaking for interaction; credit for kills; npc_identity, dialogue_id, delivery_source and delivered_count for the corresponding NPC events; recipe_id, recipe_type, recipe_serializer, output_item_id, crafted_amount and source for crafting; advancement_id, criterion and complete for advancement; and dungeon/difficulty for dungeon completion. Optional craft metadata can be absent.

Photography payload

The Exposure bridge chooses the awarded server player, then the executing server player, then a player holder. Without one, no quest photo event is sent. The event source is the camera holder and the target is the nearest unremoved living entity from Exposure’s supplied frame list, measured from frame position.

Use these keys with isekaiexpansion:payload; they are generated event data, not additional fields in photograph.data. “When recorded” means the corresponding metadata is present in the Exposure frame.

Photo entity lists combine all valid frame subjects; the ordinary entity filter examines only the nearest target. To require a type anywhere in the frame, test entity_types_in_frame. Empty string-list payloads are omitted, so a missing list passes only when that payload condition has require_present: false.

Content triggers and sequence state

On normal progress, objective_progressed runs after the value changes; objective_completed follows when that change first completes the objective. A manual content event does not itself increment objective progress. Actions run in authored order whenever their trigger’s conditions pass; there is no implicit once-only flag. The built-in spawn action can therefore run repeatedly.

Sequence progress is stored by id across the entire active quest, so reuse deliberately. A sequence remembers satisfied steps and stays true after the end. It examines only its current child on a callback. With nested stateful children, a child that reports a state change short-circuits the parent state write; the parent can need another callback to record its step. Do not treat nested sequences as an atomic multi-step evaluator.

Spawn action

The only built-in content action is isekaiexpansion:spawn_entities. Its data uses the fields below. Distances are blocks, angles are degrees, numeric bounds reject rather than clamp, and all authored floating-point values must be finite.

A spawn anchor is the picked position for quest_picked, the event position for progress/completion, or the supplied manual position. Radius mode ignores offset. Spread searches independently for each entity; cluster resolves a base and searches nearby for later entities. Search failure logs a warning and may produce a partial group; it does not undo objective progress or rewards.

Candidate search needs supported, collision-free space and applies the authored outdoor, fluid, visibility, structure and local connectivity policies. Same-room search is bounded to the source’s vertical neighbourhood of ±4 blocks and its node budget. The exact-offset path checks space and advanced constraints, but does not apply max_vertical_delta. Reference-dependent policies fail without a source in the same world.

The encounter limit counts unremoved entities carrying the tag in the scan box, including entities from other actions that reuse that tag. It is not a global cap or a quest-owned despawn policy. Mob initialisation runs before authored NBT, followed by command tags, persistence and targeting. Disabled actions are removed; a trigger whose entire action list is disabled is invalid.

Failure rules

delivery_item_leaves_hand fails the entire quest on a player tick when the incomplete objective’s original picker no longer holds a matching full batch. It has no “picked up once” arming stage or grace period. delivery_damage_while_carrying fails on a player-damaged trigger while that picker holds a matching full batch.

Failure checks run before progress checks for the same trigger and do not reuse the objective event-condition tree. A completed objective no longer supplies failure checks. In a multi-batch strict-carry objective, consuming a batch can leave insufficient items for the next tick, so its item requirement must still be satisfied while it remains incomplete.

Typed NBT

Ordinary JSON objects become compounds, booleans become bytes, integer tokens become int or long, and other finite numeric tokens become double. Arrays must convert to one homogeneous NBT element type; null is rejected. To force a primitive or primitive-array type, use a nested wrapper with exactly these fields:

Integer tokens must fit the signed 64-bit range before conversion; declared byte/short/int ranges are narrower. A float wrapper also rejects values that overflow finite float representation. Extra keys in a typed wrapper, mixed-type lists and unknown type names reject the quest definition.

Validation

An unknown type, missing required object, invalid bound, empty item/block predicate, unsupported delivery combination, duplicate failure type or invalid content trigger rejects the quest catalogue reload as described in Quest Data. Unknown keys are usually ignored, so placing a valid field under the wrong objective type can silently disable the intended restriction.

Explicit entity/item/block IDs are checked against their registries. Recipe, advancement, dialogue, dimension, dungeon and many tag references primarily undergo identifier parsing and later matching; a syntactically valid missing target can load and never progress. An enabled spawn action requires a registered entity type but may still fail to find a usable position at execution.

Reloading

Objectives reload with their enclosing quests. Active progress is keyed by quest ID and objective ID; there is no automatic semantic migration when you change types, targets, required counts or sequence IDs. Re-test an active quest as well as a newly accepted one after changing a definition.

The server remains authoritative. Client data is a presentation projection, not the full executable content-trigger tree. Translation/resource changes require their own client resource reload.

Related

• Quest Data — complete quest files, picking and cooldowns.
• Quest rewards — recipient selection and reward execution.
• Quest runtime — event hooks, saved state and debugging.
• NPC dialogue — dialogue and menu integration.