QuestPlus

Escort NPCs along a road network, a daily rotating quest pool and a combat status fact.

Privatev0.0.2Quests & narrative

RequiresTypeWriter0.9.0-beta-177 (BTC build)Quest (TypeWriter extension)Basic (TypeWriter extension)RoadNetwork (TypeWriter extension)Entity (TypeWriter extension)QuestCodex (TypeWriter extension)optional

Built for the BornToCraft network. This extension is documented for reference and is not distributed.

Support

Overview

QuestPlus extends the TypeWriter Quest extension with an escort objective, a daily rotation of quests and a combat status fact. In an escort, an NPC walks from checkpoint to checkpoint along a road network and the player has to keep it alive and stay close. A temporary quest definition decides when a set of quests is available and which quests are picked for the day.

Escorts use the Quest, Basic, RoadNetwork and Entity extensions: the route comes from a road network, the NPC is an entity instance, and the compass or path stream for the player comes from the Quest compass of QuestCodex because the escort objective is locatable.

Quest status indicators above NPC heads (npc_status_override) are not part of QuestPlus. They are provided by UiCore and its nameplates.

Features

• Escort objective — an NPC follows a route of road nodes, pauses at each checkpoint and must reach the end.
• Failure and reset rules — the player must stay within a guard radius, the NPC can be hurt by mobs, and a time limit can apply.
• Checkpoint triggers — start, checkpoint, lost, recovered, reset, complete and fail triggers, plus ambush triggers per checkpoint.
• Escort display — optional scoreboard and boss bar showing checkpoint, time and health.
• Escort actions — start, advance, reset and stop an escort from any sequence.
• Temporary quests — a rotating pool: availability by day of week, hours and cron, a number of quests picked each day, and a completion limit.
• Combat status — a fact that is 1 for some seconds after the player hits or is hit.
• Hideable objectives — hide an objective until its quest is tracked.
• Placeholders — escort progress, health and time, and the quests of the day with a countdown to the next rotation.

Installation

1. Install the TypeWriter extensions Quest, Basic, RoadNetwork and Entity that QuestPlus declares as dependencies.
2. Optional: install QuestCodex to show escort waypoints to the player.
3. Put the QuestPlus JAR in plugins/Typewriter/extensions/ and restart the server.
4. Build a road network with the RoadNetwork extension for your escort route, see Getting started.

Getting started

Create an escort mission:

1. In the TypeWriter web panel, create a road network with the RoadNetwork extension and place the nodes your NPC must pass. Keep the edges up to date: if the path cannot be computed, the NPC does not reach its node.
2. Add a Path Escort Activity entry. Set roadNetwork, list the node ids in nodes in walking order, and set idleActivity to what the NPC does once the route is finished.
3. Create an entity instance for your escort NPC and set its activity to this Path Escort Activity. The instance must belong to an active audience, because QuestPlus uses the display TypeWriter already runs for it.
4. Add an Escort Objective entry. Set quest, npc (your entity instance) and display. Tune maxHealth, guardRadius, loseToleranceSec, spawnRadius and startRadius, and optional globalTimeLimitSec.
5. Link the triggers: onEscortComplete to what should happen on success (for example an action that sets a fact for the next quest step) and onEscortFail to the failure handling.
6. Let the player reach the escort. The escort starts on its own when a player in the objective's audience comes within startRadius of the first node. To start it from a dialogue or an event instead, use Escort Start with objective.
7. Each time the NPC stops at a checkpoint, use Escort Next (for example after a dialogue line or a cleared ambush) to make it walk to the next one.
8. Publish and test: the NPC appears near the first node, and the escort begins when you come within startRadius of it.

Use /escort debug resolve <objective> to check that the first node and the radii are resolved.

Ambushes

Fill ambushes with a checkpointIndex and triggers. When the escort reaches that checkpoint, the triggers fire once, for example to spawn mobs with another extension.

How it works

When an escort starts, QuestPlus creates an invisible health holder for the NPC that only the escorted player can see. Nearby mobs within guardRadius target it. The NPC loses health from mob hits (mobHitDamage) and can regenerate (regenPerSec). Players cannot hurt it. It is fully protected if invulnerable is on.

The NPC walks to the next road node, which counts as reached once the NPC is within nodeReachRadius of it, then waits until an Escort Next action releases it. Reaching a checkpoint fires onCheckpoint and the matching ambush triggers. After the last node, onEscortComplete fires.

Reset. The escort goes back to its last checkpoint, with full NPC health, when the NPC dies or the player dies, or when the player stays farther than guardRadius for loseToleranceSec seconds. onEscortLost fires when the player goes out of range and onEscortRecovered when they come back. onEscortReset fires on a reset.

Failure. The escort fails when globalTimeLimitSec runs out, when the player quits, when the NPC disappears, or on Escort Stop. onEscortFail fires.

An Escort Reset action cancels the escort without any failure trigger.

Temporary quests

A Temporary Quest Definition is an audience filter. Its children are shown to players only while it is active:

• Availability. It is active on the daysOfWeek listed, between startTime and endTime (HH:mm) if set, and when cronExpression matches if set.
• Daily pick. questsPerDay quests are chosen at random from quests each day. The choice is deterministic for a given day and entry, changes at resetTime, and is saved in a Temporary Quest Artifact referenced by artifact.
• Completion limit. With maxCompleted above 0, players who completed that many of the day's quests no longer see the children. The counter is saved in the artifact and resets with the day.

The daily pick is exposed through placeholders and completion counting. The filter itself does not hide the quests that were not picked: use the placeholders in your menus, or design your quest availability so that only the quests you show are reachable.

Combat status

The Combat Status Fact is 1 while the player has hit an entity or been hit by one within the last thresholdSeconds (10 by default), and 0 otherwise. Use it in criteria to block fast travel, dialogue or logout rewards during a fight. It only tracks combat that involves a player.

Placeholders

MiniPlaceholders tags for MiniMessage text.

Escort, for the escorted player. When no escort is active the values are neutral.

Placeholder	Returns
<escort_checkpoint>	Current checkpoint as n/total, 0/0 when inactive.
<escort_time>	Seconds elapsed, or seconds remaining when the objective has a time limit.
<escort_health>, <escort_health_max>	Health of the escort NPC and its maximum, 0 when inactive.
<escort_is>	1 when an escort is active.
<escort_is_max>	1 when the last checkpoint is reached.

Temporary quests, where id is the id of the Temporary Quest Definition entry.

Placeholder	Returns
<tempquest_active_quests:id>	Ids of today's quests, separated by a comma.
<tempquest_time_remaining:id>	Time before the next rotation as HH:MM:SS.
<tempquest_quests_per_day:id>	Number of quests picked per day.
<tempquest_quest_name:id:n>	Display name of the nth quest of the day, starting at 1.
<tempquest_quest_desc:id:n>	Display text of the nth quest.

Commands

Command	Description
/escort debug start <objective>	Start an escort for yourself (player only).
/escort debug stop	Stop your escort.
/escort debug skipnode	Advance your escort to the next checkpoint.
/escort debug scan	Run the automatic start scan now.
/escort debug resolve <objective>	Print the first node and the radii of an objective.

The <objective> is the id or the name of an Escort Objective. The command needs questplus.escort.debug.

Permissions

Permission	Grants
questplus.escort.debug	/escort debug. It has no default, so only operators have it unless you grant it.

Entries

9 entries, generated from the extension source.

Actions4

• Escort NextAdvance escort to next checkpoint
• Escort ResetReset escort objective
• Escort StartStart an escort objective
• Escort StopStop the current escort objective

Objectives1

• Escort ObjectiveEscort an NPC along a route

Facts1

• Combat Status FactCombat Status Fact

Audiences1

• Temporary Quest DefinitionActivates a rotating subset of quests each day

Activities1

• Path Escort ActivityMoving along a path for escort

Artifacts1

• Temporary Quest ArtifactStores today's quests and reset time

Troubleshooting

The NPC never appears. The log says "npc instance missing" or "has no display registered in the AudienceManager". The npc of the objective must be an entity instance that belongs to an active audience. Run /escort debug resolve <objective> and check that the instance exists.

The log says "is missing a path_escort_activity". The entity instance used as npc must have a Path Escort Activity as its activity.

"node ... not found" or "has no nodes". The nodes of the activity list ids that are not in the selected roadNetwork, or the list is empty. Pick the nodes again after editing the network.

"navigation ... ended N blocks away from the node. The road network could not produce a walkable path; recalculate its edges." The NPC cannot walk to the node. Recalculate the edges of the road network and check the terrain between the nodes.

The escort does not start by itself. The player must be in the objective's audience (the quest active and the objective's criteria true), in the same world as the first node and within startRadius of it. Otherwise start it with Escort Start. The NPC only spawns when the player is within spawnRadius of the first node.

The escort resets immediately. The player is farther than guardRadius for longer than loseToleranceSec, or the NPC is dying from mob hits. Raise the radius or the tolerance, lower mobHitDamage, or turn invulnerable on.

The NPC stops at every node and does not continue. This is by design: it waits for Escort Next at each checkpoint.

Temporary quests are all hidden. The definition is only active on its daysOfWeek, between startTime and endTime, and when cronExpression matches. Check them, and the maxCompleted limit.

Related extensions

• QuestCodex — compass and path to the escort waypoints.
• UiCore — quest status indicators above NPCs (npc_status_override).