Command Authoring, Books, Command Files, and `db:` Action Lines

Duck Blocks gives you several different ways to build a trigger's command list. That matters because a one-line kiosk button, a cinematic machine, and a reusable event controller should not all be authored the same way.

The four practical authoring routes

These are the command-authoring paths that matter most in live use:

• the Commands button in the trigger editor
• direct command commands such as /duckblock add
• writable-book editing for long multi-line lists
• reusable text files loaded with add-from-file

If you are building one simple machine, the GUI is usually fastest. If you are building a reusable machine family, command files are usually cleaner.

What the Commands GUI is for

The in-game Commands menu is the day-to-day editor for one DuckBlock.

It lets you:

• page through the current lines
• remove individual lines
• copy a line back into chat for review
• add one line quickly through chat
• open a writable-book editor for longer lists
• clear the whole command list

Use it when the machine already exists and you are tuning its exact response.

When chat input is enough

Simple one-line jobs are still fine through direct commands or the quick chat prompt:

/duckblock add console say Station control activated
/duckblock add player warp lobby

That is a good fit for:

• one announcement
• one warp
• one scoreboard or objective command
• one test line while you are validating the trigger

Do not force long command sets into chat if the machine is getting complicated.

When the writable book is the right tool

The book editor is the safer route for long or messy command lists because it gives you room for:

• multiple lines
• long JSON or component-heavy commands
• cleaner editing without chat length pressure

Use the book flow when:

• one DuckBlock drives several steps
• the lines are long enough that chat editing becomes annoying
• another admin needs to review the exact command list later

When add-from-file is better than both

Duck Blocks has a reusable command-file folder:

plugins/DuckBlocks/commands/

The built-in note for that folder is direct:

Place UTF-8 text files here (e.g., amplay.txt). Use /duckblock add-from-file <filename> [console|player].

Example:

/duckblock add-from-file station_open.txt console

Use command files when:

• you want several machines to share the same routine
• you are building event bundles or reusable world systems
• you want the command list versioned outside the GUI

This is one of the cleanest ways to keep a large Duck Blocks library maintainable.

Normal commands versus db: action lines

Duck Blocks command lists can mix two different families of lines.

Normal commands

Use normal commands when the job belongs to:

• the console
• the activating player
• another plugin
• a server-wide system such as objectives, warps, quests, economies, or round control

db: internal action lines

Use db: lines when the behavior belongs inside Duck Blocks itself:

• sound playback
• particles
• particle shapes
• messages
• action bars
• titles
• display scaling, hiding, showing, or text changes

This split is what makes Duck Blocks feel like an engine instead of just a command wrapper.

Useful db: action families

From the current source and GUI builders, the public action families include:

• db:message
• db:actionbar
• db:title
• db:particle
• db:particlefx
• db:sound
• db:display hide
• db:display show
• db:display scale
• db:display text
• db:display itemhand
• db:display kill

The GUI exposes dedicated builders for several of these, including sound, particle, particle-shape, and display-action flows, so builders do not need to type every line from scratch.

Example: mixed machine authoring

commands:
  - "say {player} opened the station gate."
  - "db:sound BLOCK_PISTON_EXTEND vol=1.0 pitch=1.0 audience=nearby mode=origin range=24"
  - "db:particlefx ring ELECTRIC_SPARK 1.4 96 0.0 0.0"
  - "db:actionbar Gate unlocking..."

This is a good Duck Blocks pattern:

• one normal command for server logic
• one sound for feedback
• one particle shape for spectacle
• one player-side message for readability

Good command-authoring habits

• Keep one line per job whenever possible.
• Use book editing before chat becomes frustrating.
• Move repeated routines into commands/*.txt.
• Use db: lines for local machine feedback instead of sending everything through server commands.
• Keep one clean test machine nearby so you can validate changes quickly.

Best next pages

• placeholders, Player Context, and Command Handoffs
• trigger Editor, Core Controls, and Machine Layout
• effects YML: Sounds, ParticleFX, and Combo Presets