First Boot, Trigger Types, and the File Map

Duck Blocks is easiest to understand in two layers:

• the plugin generates a small runtime file surface
• the real authoring happens in the GUI and then saves back into those files

That is why first boot matters. It is the moment where you confirm the plugin is ready for real builders instead of treating it like a black box.

What should appear after first boot

After you place the jar in plugins/ and start the server, Duck Blocks should generate:

• config.yml
• duckblocks.yml
• duckblocks-state.yml
• animations.yml
• effects.yml
• commands/

If those files exist and the plugin starts without errors, your first authoring surface is ready.

What each trigger identity is for

Duck Blocks supports three main trigger identities, and they are easiest to use when you choose them deliberately.

Block trigger

Use a block trigger when the location itself is the machine.

Good fits:

• hidden redstone devices
• precise world anchors
• adventure-map buttons
• invisible logic blocks embedded in the environment

ArmorStand trigger

Use armor-stand mode when you need the older compatibility path.

Good fits:

• preserving older content
• fallback situations where an existing map already depends on stand behavior

For most new public builds, this should not be the first choice.

Interaction trigger

This is the modern default for most new builds.

It is the best fit for:

• clean clickable hitboxes
• display-backed props
• timelines and motion
• travel paths
• walkable or mountable movement
• optional ModelEngine-linked visuals

If you are building a button, prop, pedestal, moving platform, or rideable machine, start here.

Good first-boot workflow

The safest first proof looks like this:

1. Run /duckblock gui
2. Open Create DuckBlock
3. Choose Display DuckBlock (Item) while holding a visible test item
4. Open the trigger editor
5. Add one visible action such as a message or sound
6. Confirm the trigger works before adding travel, redstone, or timelines

That gives you one reliable proof that the plugin, display, clickbox, and save flow are all healthy.

Why the YAML still matters

Even if you prefer the GUI, it helps to know the saved result has a readable structure in duckblocks.yml.

schema: 9
triggers:
  - sid: 1
    commands:
      - "db:message Welcome to the machine."
      - "db:sound UI_BUTTON_CLICK vol=1.0 pitch=1.0 audience=player mode=origin range=0"
    execMode: CONSOLE
    cooldownMs: 0
    oneTime: false
    redstoneEnabled: false
    renderMode: DISPLAY_ITEM
    interactionWidth: 1.4
    interactionHeight: 1.4

You do not need to memorize every saved field. You do need to understand that the GUI and the YAML are part of the same authoring pipeline.

What to learn next

Once first boot is clean, move into:

• config YML: Runtime Defaults and Save Policy
• main Menu, Create Flow, and the Help Command
• trigger Editor, Core Controls, and Machine Layout

Early mistakes to avoid

• Do not start by hand-editing duckblocks-state.yml.
• Do not build a giant library before you have one good test trigger.
• Do not mix block, armor-stand, and interaction styles randomly without deciding why each one exists.
• Do not jump into travel paths before the trigger itself can already fire cleanly.