Admin Runtime, State, and Live Troubleshooting

Duck Blocks is meant to be edited live, so runtime troubleshooting matters just as much as authoring. This page is the operations view: what gets saved, what the debug logs mean, and what to check when a machine does not behave the way you expected.

What duckblocks-state.yml is for

duckblocks-state.yml is the persistence layer for runtime state. It is not the place where you design the machine itself.

Use it for:

• understanding that state is being saved
• confirming schema and persistence are healthy
• checking whether restart-safe behavior is enabled

Do not treat it as your main content file. The machine definitions live in duckblocks.yml.

Save behavior that matters

The global save policy comes from config.yml:

save-state-on-shutdown: true
auto-save-interval-seconds: 120

That means the practical admin questions are:

• does the server save often enough for your use case
• do you trust shutdowns to be clean
• are builders making live edits that should survive a restart quickly

What the carry debug logs are for

If you are using moving, walkable, or mountable structures, the carry debug logs are one of the most useful troubleshooting tools in the whole plugin.

The live log format exposes terms such as:

• CARRY[smart]
• TOP_SURFACE
• profile=down_diag
• sink
• peek
• stationaryColliders
• sessionColliderCount
• FAILMOVE CLIPPED
• rescue=floor_clamp

Those lines tell you how the platform is trying to carry the player, whether the collider set is stable, and whether the machine is fighting gravity, clipping, or slope handling.

Reading the real carry log language

From the live debug logs you provided, these are some of the most useful practical clues:

TOP_SURFACE

The carry system believes the player is riding on the top face of the moving platform.

sink

A non-zero sink value usually means the carry system thinks the rider is dropping into the platform or losing surface stability.

peek

This is one of the lift or surface-assist values. A machine with lots of trouble stepping upward or holding a clean top surface will usually make you care about this quickly.

sessionColliderCount

This helps you confirm how many active helper colliders exist for the current moving session.

FAILMOVE CLIPPED

This is one of the strongest signs that the route, collider shape, or walk settings are pushing a player into bad geometry.

rescue=floor_clamp

This means the carry system is actively trying to recover the rider onto a stable floor relationship instead of letting the move fail completely.

Common runtime problems

The trigger exists, but clicking does nothing

Check:

• the hitbox size in the display or interaction editor
• whether the move tool or path builder is still active
• whether the trigger is hidden or the wrong entity was selected
• whether the commands list is empty

Next pages:

• trigger Editor, Commands, Effects, and Placeholders
• displays, Hitboxes, and ModelEngine

Redstone power changes, but the machine does not fire

Check:

• redstoneEnabled
• edge mode (ON, OFF, or BOTH)
• debounce value
• per-player range settings
• skipIfEmpty
• requirePlayerPlaceholder

Next page:

• activation Sources, Redstone, and Player Proximity

The visual is wrong, but the hitbox still works

Check:

• render mode
• display item, block, or text source
• visual offsets versus hitbox offsets
• interpolation settings
• whether the display was hidden intentionally

Next page:

• displays, Hitboxes, and ModelEngine

A moving platform carries players badly

Check:

• walkable
• mountable
• walkPlatformType
• carryMode
• walkYOffset
• walkPadding
• walkMaxVerticalStepPerTick
• levitation or up-speed assists

If the machine is advanced, read the carry log before changing three different settings at once.

Next page:

• travel Paths, Walkable Platforms, and Rideable Structures
• travel GUI, Path Builder, Waypoints, and Carry

Timelines or effects feel too heavy

Check:

• whether the behavior should be a simple animation instead of a timeline
• whether the timeline should be NEARBY instead of ALWAYS
• whether the effect belongs in a reusable preset instead of repeated inline lines

Next pages:

• animations, Effects, and the Timeline Orchestrator
• effects YML: Sounds, ParticleFX, and Combo Presets

Good admin habits on a live server

• Keep one clean test DuckBlock for validating config changes quickly.
• Prefer presets in animations.yml and effects.yml over copy-pasting the same long lines everywhere.
• Use the GUI as the source of truth for live edits, then review the saved YAML afterward.
• Turn to the carry debug logs early when a moving structure feels wrong.
• Split large systems into multiple cooperating DuckBlocks instead of forcing one trigger to do everything.