Skip to content
DarkBladeDev Docs

Virtual Display Animations and Keyframes

CraftingEngine provides a next-generation visual animation engine built on top of Minecraft 1.20+ Display Entities (ItemDisplay, BlockDisplay) and streamed entirely through PacketEvents 2.14.0 synthetic network packets.

1. Architectural Highlights

  • Zero Physical Entities: No Bukkit entities are spawned in world chunks. Display elements exist strictly in client-side memory, preventing chunk bloat, lag spikes, and entity leak bugs.
  • Interpolation & Easings: Native client interpolation combined with all 30 standard Penner easing functions (Linear, Quad, Cubic, Quart, Sine, Expo, Circ, Back, Elastic, Bounce).
  • Procedural AST Formulas: Animate rotation, oscillation, and orbital paths using mathematical expressions (sin, cos, lerp, clamp).
  • 3D Pivot Transformations: Rotate tools or items around custom rotation pivots (e.g. rotating a hammer around its handle instead of its center of mass).

2. Animation Preset Configuration (presets/animations/*.yml)

id: "blacksmith_hammer_strike"
duration: 40           # Cycle length in ticks (40 ticks = 2.0s)
loop_mode: "LOOP"      # LOOP | ONCE | HOLD | PING_PONG


actors:
  - id: "hammer"
    role: "TOOL"
    display_type: "ITEM"
    item_transform: "THIRDPERSON_RIGHTHAND"
    billboard: "FIXED"
    pivot: [0.0, -0.45, 0.0] # Rotate around the base of the handle


    # Discrete keyframe timeline
    keyframes:
      - tick: 0
        translation: [0.0, 0.8, 0.0]
        rotation: [-45.0, 0.0, 0.0]
        easing: "EASE_OUT_QUAD"
      - tick: 15
        translation: [0.0, 0.05, 0.0]
        rotation: [15.0, 0.0, 0.0]
        easing: "EASE_IN_BOUNCE"
      - tick: 40
        translation: [0.0, 0.8, 0.0]
        rotation: [-45.0, 0.0, 0.0]
        easing: "EASE_IN_OUT_CUBIC"


    # Audio-visual events triggered at exact ticks
    cues:
      - tick: 15
        sound: "block.anvil.use"
        particles:
          type: "CRIT"
          count: 8
          offset: [0.1, 0.1, 0.1]

3. Multi-Actor Orbits & Ingredient Layouts

CraftingEngine can dynamically spawn multiple items and distribute them in 3D geometric formations:

actors:
  - id: "orbiting_crystals"
    role: "INPUT_RESOURCES"
    display_type: "ITEM"
    layout:
      type: "CIRCLE"
      radius: 1.2
      height_offset: 0.5
    procedural:
      rotation_y: "time * 4.5"
      translation_y: "0.5 + sin(time * 0.1) * 0.15"

Layout Types:

  • CIRCLE: Distributes items evenly along a horizontal circumference.
  • GRID: Arranges items in a flat planar matrix above the station.
  • VERTICAL_STACK: Stacks items vertically like a totem.

4. In-Game Preview and Scrubbing

Administrators can preview and debug animations in real time without restarting:

Ventana de terminal
/cfe animation preview <preset_id>   # Spawns preview at player target location
/cfe reload animations               # Reloads all preset files from disk

Next Steps