Untitled Physics

Real-time 3D rigid-body physics engine and developer API for Paper 1.21.4 servers — powered by native Display Entities with zero client mods or resource packs required.

---

What is Untitled Physics?

Untitled Physics brings true server-side 3D rigid-body simulation to Paper 1.21.4+ without requiring players to install any client mods or resource packs. Every physical object is rendered through native Minecraft BlockDisplay, ItemDisplay, and TextDisplay entities paired with shape-fitted Interaction hitboxes and a jitter-free Split-Impulse Projected Gauss-Seidel (PGS) constraint solver.

It works out of the box in two modes:

1. Standalone Server Plugin — convert structures into physical or destructible 3D objects, manipulate bodies with interactive physics wands, connect blocks with ropes/springs/hinges, and fine-tune 34 world reaction rules.
2. Developer Library (UntitledPhysics.get()) — a clean, zero-NMS Java API for spawning custom multi-part 3D bodies, motorized joints, force fields, raycasts, and listening to physical collision/interaction events in your own plugins.

(Attach Showcase GIF 5–8 sec / Прикрепить короткую GIF-анимацию 5–8 сек: взрыв ТНТ или выстрел Wind Charge рядом с выделенной постройкой в режиме breakable — блоки реалистично разлетаются, вращаются в 3D и плавно замирают на земле без дрожания)

---

Key Features

1. Exact VoxelShape Colliders & Hitboxes

No phantom full-cube air boxes around non-cubic blocks:

• 1:1 Block Geometry: Automatically reads Paper's Block#getCollisionShape() (VoxelShape) for slabs, stairs (straight, corner, upside-down), trapdoors, fences, walls, anvils, cauldrons, lecterns, lanterns, chains, and carpets, shifting the collider to its exact volume-weighted Center of Mass (COM) via the Parallel Axis Theorem.
• Subdivided Interaction Hitboxes: Click and attack hitboxes wrap each sub-box of the VoxelShape so players can click and shoot arrows right through the empty cutout of stairs or arches.

(Attach Screenshot / Прикрепить скриншот с включённым /untitled debug hitboxes: на земле лежат физическая дубовая ступенька, полублок, люк и наковальня — отчётливо виден каркас коллайдера точно по L-образной форме ступеньки)

2. 3D Region Conversion & Destructible Structures

Turn any building, tree, bridge, or statue into a physical 3D object:

• Select Pos1 and Pos2 using the Region Selector wand (/untitled selwand) or /untitled pos1 & /untitled pos2 with a live particle wireframe preview.
• /untitled convert compound — merges adjacent full cubes via 3D Greedy Voxel Meshing and hides enclosed interior blocks (Interior Culling) to maximize client FPS and keep server MSPT minimal.
• /untitled convert breakable — welds neighboring blocks with breakable FixedJoint constraints (breakImpulse) so explosions and heavy impacts shatter walls and roofs into pieces.

(Attach Before/After Screenshot or GIF / Прикрепить GIF или 2 скриншота «До и После»: выделение небольшой башни рамкой Region Selector -> /untitled convert breakable -> попадание взрыва и обрушение конструкции)

3. Calibrated to Vanilla Minecraft 1.21.4 Constants

Simulation values are matched to real Minecraft mechanics rather than arbitrary numbers:

• Gravity: -16.0 m/s² (0.04 blocks/tick², matching vanilla FallingBlock, PrimedTnt, Item, and Boat free-fall; includes entity = -32.0, earth = -9.81, moon = -3.7, and zero presets).
• Pistons, Slime & Honey: Piston-driven Slime Blocks launch bodies at exact vanilla 20.0 m/s (1.0 block/tick), Honey Blocks carry bodies cleanly by 1.0 block, and non-sticky retracting pistons wake resting bodies without false pulling.
• Explosions: Uses exact vanilla blast radius 2.0 × power (TNT = 4 → 8m, Creeper = 3/6 → 6/12m, End Crystal = 6 → 12m, Bed/Anchor = 5 → 10m, Wind Charge = 2.6m/3.0m) with raycast wall occlusion and optional temporary 3D block debris.
• Hydrodynamics & Surfaces: 9-point Archimedes buoyancy in water and lava, river & Nether/Overworld lava flow currents, Soul Sand / Magma bubble columns, cobweb & powder snow damping, bed (0.66) & slime (0.85) bounce, hay bale impact absorption, Blue Ice < Packed Ice < Ice friction tiers, and exact Attribute.ENTITY_INTERACTION_RANGE melee reach (3.0m Survival / 5.0m Creative).

(Attach Screenshot or GIF / Прикрепить скриншот или GIF: деревянные ящики плывут по течению воды и подбрасываются колонной пузырей от песка душ, а тяжёлая наковальня лежит на дне)

4. Interactive Physics Wands

Run /untitled wand [all|gravity|selector|voxelizer|linker] to obtain:

• Gravity Gun (BLAZE_ROD) — RMB to grab/carry any dynamic 3D body in mid-air, Sneak + Scroll to adjust distance, LMB to launch forward.
• Region Selector (BREEZE_ROD) — LMB = Pos1, RMB = Pos2, Sneak + RMB = convert region into physics.
• Voxelizer (AMETHYST_SHARD) — RMB converts a single world block into a zero-shift 3D body; Sneak + RMB merges a 3×3×3 cluster; LMB creates a breakable welded cluster.
• Joint Linker (TRIPWIRE_HOOK) — RMB two bodies (or one body and a world block) to link them; Sneak + LMB cycles joint mode (SPRING, ROPE, BALL_SOCKET, BREAKABLE_WELD).

5. Claim Protection, TPS Safety & 34 Reaction Flags

• Claim & Container Protection: Fires cancellable BlockBreakEvent probes before converting blocks (compatible with WorldGuard, GriefPrevention, Towny, Lands, and spawn protection), enforces WorldBorder, blocks unbreakable/technical blocks (bedrock, portals, spawners, command blocks), and skips InventoryHolder containers (skip-containers: true) so player loot is never lost.
• 34 Toggleable Reaction Flags: Run /untitled reactions for an interactive clickable chat menu controlling all 34 flags across 8 categories (globally, per-world, per-body, or per-player).
• Per-Admin Live 3D Debugger: Run /untitled debug to inspect OBB/compound collider wireframes, contact points, velocity vectors, joint tension, and real-time MSPT in the ActionBar (visible only to the admin who enabled it).
• Multi-Language (messages.yml): Built-in English (en) and Russian (ru) locales with hot-reload (/untitled reload) and custom language support.

(Attach Screenshot / Прикрепить составной скриншот: слева — интерактивное меню /untitled reactions в чате, справа — режим /untitled debug со строкой телеметрии над хотбаром)

---

Requirements & Installation

• Server Software: Paper 1.21.4 or compatible fork (Purpur). Folia regional multithreading and Spigot/CraftBukkit without Paper's VoxelShape / Adventure APIs are not supported.
• Java Version: Java 21 or newer.
• Client: Vanilla Minecraft 1.21.4 (no client mods needed).

1. Drop Untitled.jar into your server's plugins/ folder and restart the server.
2. Edit plugins/Untitled/config.yml and plugins/Untitled/messages.yml if desired (switch default language anytime with /untitled lang en or /untitled lang ru).
3. Configure LuckPerms permissions if granting tools or commands to non-operators.

---

Commands & Permissions

Primary command: /untitled (aliases: /uphysics, /uphys, /up).

Command	Permission	Description
/untitled spawn <box|sphere|capsule|item|text> ...	untitled.command.spawn	Spawn a physical 3D Display body
/untitled wand [all|gravity|selector|voxelizer|linker]	untitled.command.wand	Give interactive physics wand tools
/untitled selwand / pos1 / pos2 / selclear	untitled.command.region	Select or clear a 3D region
/untitled convert [compound|breakable] [cut|keep]	untitled.command.region	Convert selected structure into a compound or breakable body
/untitled voxelize [radius] [compound|breakable]	untitled.command.region	Convert blocks around your crosshair into 3D physics
/untitled reactions [list|toggle|enable|disable|body|ignore|reset]	untitled.command.reactions	Configure all 34 physics reaction flags
/untitled debug [toggle|all|off|actionbar|particles|hitboxes|contacts|velocity|joints]	untitled.command.debug	Toggle real-time 3D particle & ActionBar debugger
/untitled gravity <default|entity|earth|moon|zero|invert | x y z>	untitled.command.sim	Change world gravity vector
/untitled explode [strength] [radius] / pause / step [ticks]	untitled.command.sim	Trigger shockwave, pause simulation, or step ticks manually
/untitled stats	untitled.command.stats	View world body counts, contacts, and step time (ms)
/untitled clear	untitled.command.clear	Remove all physics bodies in the current world
/untitled lang [code] / /untitled reload	untitled.command.lang / .reload	Switch active locale or hot-reload config.yml & messages.yml

Additional Permission Nodes:

• untitled.* / untitled.admin (default: op) — full access to all commands, wands, and interactions.
• untitled.wand.gravity, untitled.wand.selector, untitled.wand.voxelizer, untitled.wand.linker (default: op) — required to actively use each wand item.
• untitled.interact.push, untitled.interact.attack, untitled.interact.fish, untitled.interact.click (default: true) — natural gameplay interactions (walking into bodies, punching/shooting, fishing rod pulling, right-clicking).

---

Developer API Quickstart

Add depend: [Untitled] to your plugin.yml and compile against Untitled.jar:

dependencies {
    compileOnly("io.papermc.paper:paper-api:1.21.4-R0.1-SNAPSHOT")
    compileOnly(files("libs/Untitled-1.0.0.jar"))
}

import dev.untitled.physics.api.PhysicsEngine;
import dev.untitled.physics.api.UntitledPhysics;
import dev.untitled.physics.body.PhysicsMaterial;
import dev.untitled.physics.body.RigidBody;
import dev.untitled.physics.config.PhysicsReactionFlag;
import dev.untitled.physics.dynamics.joint.HingeJoint;
import dev.untitled.physics.math.Vec3;
import org.bukkit.Location;
import org.bukkit.Material;
import org.bukkit.util.BoundingBox;

public void spawnMechanism(Location loc) {
    PhysicsEngine engine = UntitledPhysics.get();

    // 1. Spawn a block body with automatic VoxelShape compound collider & fitted Interaction hitboxes
    RigidBody stairs = engine.spawnBlockBody(
        loc, Material.OAK_STAIRS.createBlockData(), Vec3.ONE, PhysicsMaterial.WOOD
    );

    // 2. Attach a motorized HingeJoint (revolving door, windmill, drawbridge)
    HingeJoint hinge = new HingeJoint(stairs, null, Vec3.fromLocation(loc), Vec3.UNIT_Y)
        .enableMotor(3.0, 100.0);
    engine.getWorld(loc.getWorld()).addJoint(hinge);

    // 3. Convert a 3D world BoundingBox into a greedy-meshed compound body
    engine.convertRegionToCompoundBody(loc.getWorld(), new BoundingBox(0, 64, 0, 6, 70, 6), true);

    // 4. Override individual reaction flags per body
    stairs.reactions().set(PhysicsReactionFlag.EXPLOSION_SHOCKWAVE, false);
}

Custom Bukkit Events (dev.untitled.physics.api.event):

• RigidBodyCreateEvent & RigidBodyRemoveEvent
• RigidBodyCollisionEvent (contact point, normal, normal impulse, second body or hit world block)
• RigidBodyInteractEvent (Cancellable — ATTACK_IMPULSE, RIGHT_CLICK, GRAB_START, GRAB_RELEASE)
• PhysicsJointBreakEvent (fired when a joint exceeds its breakImpulse / maxImpulse)

---