Craft Engine

CraftEngine blocks, furniture and items in quests, plus per-player quest zones.

Paidv1.1Integrations

RequiresTypeWriter0.9CraftEngineQuest (TypeWriter extension)

Buy on VoxelBuy on BuiltByBitSupport

Overview

Craft Engine connects CraftEngine to TypeWriter. Your custom blocks, furniture and items become things a quest can react to: events when a player breaks, places or clicks them, objectives that count them, facts and variables that read what a player holds or looks at, and actions that place, replace or remove them.

The second half of the extension is the quest zone. A quest zone gives every player their own version of an area. What a player breaks, places or changes is recorded for that player only, sent to them as packets, and given back when they return. The real world is never written to, so leaving a zone costs nothing and nothing is left half done if the server stops in the middle of a quest. A zone can also be shared by a group, so a party clears a room together.

The extension is written for Paper and Folia: every world or inventory change runs on the region that owns it.

Features

• Block and furniture events — react to custom blocks and furniture being broken, placed, interacted with or hit, including refused placements.
• Placement rules — refuse a placement or a hit unless the player holds a permission or matches criteria.
• Counting objectives — break, place or replace custom blocks and furniture as a quest objective; each position counts once per player.
• World actions — place, remove or replace a block or a piece of furniture, and store your own data on placed furniture.
• Quest zones — a per-player (or per-group) view of blocks and furniture, remembered between visits.
• Inventory swap — take a player's whole inventory, or only chosen items, on entering a zone and give it back on leaving.
• Fake block audience — show a fixed set of blocks and furniture to an audience without recording anything.
• Item tools — give or remove CraftEngine items by id, and react to picking up, dropping or eating them.
• Facts, variables and audiences — read the held item, the block or furniture being looked at, cooldowns, and group players by what they hold or sit on.

Installation

1. Install CraftEngine on your server. The extension is built against CraftEngine 26.8.
2. Make sure the TypeWriter Quest extension is installed. It provides the quest and objective entries used by the objectives.
3. Download the extension from the stores (see the buttons in the panel above) and put the JAR in plugins/Typewriter/extensions/.
4. Restart the server. In the log you should see [CraftEngine] CraftEngineExtension initialized successfully.

Getting started

This walkthrough gives each player their own breakable seal in a puzzle room.

1. In the web panel, open a manifest page and add a Quest State Artifact. Leave artifactId as generated.
2. Add a Quest Zone Audience and set artifact to the artifact you just created. Leave zoneId empty so it uses the entry id, and keep trackBlocks on.
3. Nest the zone audience under the audience that decides who is in the room (for example an area audience or a quest audience). Players who enter it get their own view.
4. On a sequence page, add an On Block Interact event for your seal block. It triggers a Set Quest Block action.
5. In the action, set artifact and zoneId to the same values as the zone (copy the zone entry id), bind location to the position of the event, and set blockId to the broken seal (namespace:broken_seal). Leave it empty to show air.
6. Add a Clear Quest State action where the quest ends, so the room can be solved again.
7. Publish, then check with two players: each one opens their own seal and the other still sees it intact.

tip

For a plain counting task, you do not need a zone: add a Break Block objective, fill item with the block id and set amount.

How it works

A change made in a zone is a deviation: a block sent to one player on top of the real one, a piece of the world's furniture hidden from one player, or a ghost, a piece of furniture that exists for that player only. A ghost can be right-clicked and broken by its viewers, but it has no collision for anyone.

Collision always follows the world. A block a player broke still blocks them, a block they placed can be walked through, and a hidden world furniture still stops the player who cannot see it. Build zones where the change is something to see and use, not something to stand on.

State is written to the artifact a couple of seconds after the last change, and immediately when a player leaves a zone or the server stops. A server that is killed instead of stopped can lose the last seconds.

Configuration

The extension has no config file. The text of objective lines can be changed with TypeWriter snippets:

Snippet	Default
craftengine.objective.display	<display> <dark_gray>(<gray><current><dark_gray>/<gray><required><dark_gray>)
craftengine.objective.completed	<green>✔</green> <st><display></st> <dark_gray>(<gray><current><dark_gray>/<gray><required><dark_gray>)

Entries

49 entries, generated from the extension source.

Actions10

• Craftengine Clear Quest StateDrop a player's own state for a quest zone
• Craftengine Give Item ActionGive a CraftEngine item to the player
• Craftengine Remove Item ActionRemove a CraftEngine item from the player
• Craftengine Set Quest BlockChange what one player sees at a spot, inside a quest zone — a block or a piece of furniture
• Craftengine Set Quest FurnitureHide or show one piece of the world's furniture, for one player, inside a quest zone
• Place Craftengine BlockPlace a CraftEngine block at a location
• Place Craftengine FurniturePlace a CraftEngine furniture at a location
• Remove Craftengine BlockRemove the CraftEngine block at a location
• Remove Craftengine FurnitureRemove the CraftEngine furniture at a location
• Replace Craftengine BlockReplace the block or furniture at a location with another one

Events13

• Craftengine on Item Consume EventTriggers when the player consumes a CraftEngine item
• Craftengine on Item Drop EventTriggers when the player drops a CraftEngine item
• Craftengine on Item Pickup EventTriggers when the player picks up a CraftEngine item
• On Craftengine Block Attempt Place EventTriggers when a player attempts to place a CraftEngine block
• On Craftengine Block Break EventTriggers when a CraftEngine custom block is broken
• On Craftengine Block Interact EventTriggers when a CraftEngine custom block is interacted with
• On Craftengine Block Place EventTriggers when a CraftEngine custom block is placed
• On Craftengine Dispense Projectile EventTriggers when a dispenser shoots a CraftEngine projectile
• On Craftengine Furniture Attempt Place EventTriggers when a player attempts to place CraftEngine furniture
• On Craftengine Furniture Break EventTriggers when a CraftEngine furniture is broken
• On Craftengine Furniture Hit EventTriggers when a player hits CraftEngine furniture
• On Craftengine Furniture Interact EventTriggers when a CraftEngine furniture is interacted with
• On Craftengine Furniture Place EventTriggers when a CraftEngine furniture is placed

Objectives5

• Break Craftengine Block ObjectiveAn objective to break CraftEngine custom blocks
• Break Craftengine Furniture ObjectiveAn objective to break CraftEngine furniture
• Place Craftengine Block ObjectiveAn objective to place CraftEngine custom blocks
• Place Craftengine Furniture ObjectiveAn objective to place CraftEngine furniture
• Replace Craftengine Block ObjectiveAn objective to replace a block with another one

Facts8

• Craftengine Cooldown Active FactWhether a CraftEngine cooldown is currently running
• Craftengine Cooldown Remaining FactSeconds left on a CraftEngine cooldown
• Craftengine Holding Item FactWhether the player is holding a CraftEngine item
• Craftengine Item Cooldown FactTicks left on the vanilla use cooldown of an item
• Craftengine Item Count FactHow many of a CraftEngine item the player carries
• Craftengine Looking at Block FactWhether the player is looking at a CraftEngine block
• Craftengine Looking at Furniture FactWhether the player is looking at CraftEngine furniture
• Craftengine Standing on Block FactWhether the player is standing on a CraftEngine block

Audiences5

• Craftengine Fake Block AudienceShow blocks and furniture to this audience alone
• Craftengine Furniture Proximity AudienceIn audience while near a CraftEngine furniture
• Craftengine Holding Item AudienceIn audience while holding a CraftEngine item
• Craftengine Quest Zone AudienceKeep a player's own block, furniture and item state for a quest zone
• Craftengine Sitting on Furniture AudienceIn audience while sitting on a CraftEngine furniture

Variables6

• Craftengine Item in Hand ID VariableThe CraftEngine ID of the item the player holds
• Craftengine Item Property VariableA property of the CraftEngine item the player holds
• Craftengine Looking at Block ID VariableThe CraftEngine ID of the block the player is looking at
• Craftengine Looking at Furniture ID VariableThe CraftEngine ID of the furniture the player is looking at
• Craftengine Registry Ids VariableThe list of IDs CraftEngine has loaded
• Craftengine Standing on Block ID VariableThe CraftEngine ID of the block the player stands on

Sounds1

• Craftengine SoundCraftEngine Sound

Artifacts1

• Craftengine Quest State ArtifactArtifact storing per-player quest block and item state

Troubleshooting

A quest zone shows nothing and no error appears. The actions and the audience must name the same artifact, zoneId and group. A change filed under another name is written correctly but nobody reads it. When zoneId is empty on the audience, it is the audience's own entry id that you must copy.

Set Quest Block does nothing and the log says "has no zone configured". zoneId is empty on the action. Set it. For Set Quest Furniture the same applies.

The log says "cannot resolve" an id. The blockId is neither a CraftEngine block, a CraftEngine furniture nor a vanilla material. Check the id with Registry IDs. With kind set to FURNITURE, an id that is not furniture is refused instead of shown as a block.

Everyone in the zone sees the same change. The action wrote the world. The Place and Remove actions, and Replace Block set to WORLD, change the real block. Inside a zone use Set Quest Block, Set Quest Furniture, or Replace Block with audience on AUTO or QUEST_ZONE.

Replace Block does nothing for a player in two zones. With several overlapping zones and no zoneId, the action refuses and writes a line in the log. Set zoneId to the zone you mean.

A change flickers back after a long walk. A client that reloads a chunk is served the real world again, and the zone re-sends its view every refreshInterval ticks within refreshRadius blocks. Lower refreshInterval or raise refreshRadius.

The block events do not fire for a block broken in a zone. With trackBlocks on, the zone takes the action over: the break or placement is cancelled and recorded as a deviation. Advance the quest from the interact events or from Set Quest Block instead.

Related extensions

• Nexo and ItemsAdder — the same kind of integration for the other custom content plugins.