feat: add animated updates, styles, and box groups

[twme-ai]

Summary

Shapes can now change after they spawn. Updates reuse the existing Text Display entities and use Minecraft's Display interpolation, so geometry, color, and position animate on the client instead of being respawned. This is the upstream work listed in the Sculpt redesign report (TWME-TW/SculptPlugin#3, §10.1).

New API

API	Purpose
LineShape, PolylineShape, TriangleShape, ParallelogramShape with setPoints(...)	Move vertices in place
Shape#setColor / getColor	Change the background color; it fades when interpolation is set
Shape#setInterpolationDuration, builder interpolationDuration(ticks)	Animate geometry and color updates
Shape#setTeleportDuration, builder teleportDuration(ticks)	Animate translate (0–59 ticks)
Shape#translate(dx, dy, dz)	Move the rendered geometry (root-anchored shapes teleport only their anchor)
Shape#getEntityCount	Entity budget reporting
ShapeStyle + builder style(...)	Reusable appearance and animation settings
ShapeGroup	Several shapes managed as one
BoxOutline / BoxFaces + factory boxOutline / boxFaces	Animated box edges and faces through setBounds
PacketShapeFactory#batch	Group updates to several shapes into one bundle
DisplayTransform, ShapeGeometry, BoxGeometry	Platform-neutral transforms for custom renderers

Behavior

• Packet mode: all parts of a shape are updated in one VirtualEntities bundle, and each update restarts client interpolation (start delta 0 plus the requested duration).
• Growing polylines: existing segments animate, new segments appear immediately, and surplus ones are removed.
• Invalid geometry (for example, a zero-length line) is rejected before any state changes or packets are sent.
• Paper and Spigot shapes support the same updates through the Bukkit Display API.

Compatibility

• Default interface methods: the new Shape and ShapeBuilder methods are default methods, so third-party implementations still compile.
• Public API unchanged: every existing public builder and shape method is kept.
• Less duplication: Packet, Paper, and Spigot shapes now share one base class per platform instead of four copies of the lifecycle code.
• Right rotation: packet shapes now always send RIGHT_ROTATION, as identity for lines. The client already defaulted to identity, so nothing looks different; it prevents stale rotations when an entity is reused for different geometry.

Fixes

• getSegmentCount() reported 2 for a closed two-point polyline that only spawns 1 segment.
• The E2E fixture was pinned to the published 3.0.0 artifact, so it was not testing the checkout. run-e2e.sh now builds the fixture against the version it just installed.

Testing

• mvn verify: new unit tests cover the geometry, face orientation, groups, styles, and builder style propagation.
  • PacketShapeAnimationTest (mocked PacketEvents API, as in VirtualEntities) checks entity reuse, interpolation metadata, bundle framing per viewer, polyline growth and shrinkage, color fades, translate with and without a root anchor, box outlines, and rejection of invalid updates.
• integration/mineflayer/run-e2e.sh: passes on a real Paper 1.21.11 server with PacketEvents 2.14.0. After the existing rebase checks, the client:
  • receives a bundled update on the same entity with transformation_interpolation_duration = 5, a doubled line scale, and the new color;
  • sees the root anchor get pos_rot_interpolation_duration = 3 and move up one block.

🤖 Generated with Claude Code