An independent, non-official Cleanroom-only runtime hitbox and collision-query library for Minecraft 1.12.2.
面向 Minecraft 1.12.2 Cleanroom-only 环境的运行时碰撞箱与碰撞查询库。
CRL Hitbox is an independent project, not an official CleanroomMC component. Its experimental geometry foundation provides immutable, JDK-only, double-precision pointwise primitives, solid unions, and rigid-transform arithmetic. It is common/server-safe and deliberately has no Minecraft, Forge, Cleanroom, JOML, LWJGL, networking, rendering, combat, or persistence dependency.
The implemented primitives are Vec3d, Rotation3d, Aabb, Sphere, Obb, Segment3d, and Capsule, with Bounded3d, distance helpers, and explicit intersection overloads. Solid3d is sealed to the four primitive solids plus Composite; Segment3d remains a finite non-solid query primitive. Geometry is finite, closed-set, and non-certified: touching intersects, but results are ordinary IEEE-754 pointwise evaluations and are never admission, continuous-collision, terrain-non-penetration, persistence, or proof authority.
The pointwise solid-solid matrix is complete for Aabb, Sphere, Obb, and Capsule: every unordered pair is supported, and each mixed pair has both symmetric overload orders. Generic sealed dispatch preserves those typed kernels. Immutable, nonempty Composite values represent finite unions whose nested inputs are flattened into an ordered primitive-leaf sequence; their bounds are broad-phase enclosures only. Finite Segment3d queries are supported against every primitive solid and Composite, in both overload orders.
RigidTransform3d supplies immutable active point/vector mapping, inverse mapping, and explicitly ordered composition. It is arithmetic only: transformed-solid wrappers, automatic local-to-world solid projection, frame IDs, entity pose extraction, and model/bone attachment remain deferred.
PlacedSolid3d adds non-materializing rigid placement of a local solid into a caller-defined parent frame. It provides conservative parent-frame bounds plus exact pointwise placed-solid and finite Segment3d queries while retaining local AABB min/max intervals directly. Callers are responsible for placing both operands in the same parent frame.
EntityHitboxHolder adds deterministic ResourceLocation-named, entity-local PlacedSolid3d state. Effective mutations alone advance a checked monotonic revision, and EntityHitboxSnapshot captures immutable insertion-ordered values. A fresh non-sided capability provider is attached to every Entity; it is intentionally non-persistent, owns no Entity/World back-reference, and keeps server and client holders independent.
An open collider API sits above the kernel so another mod can build and update colliders without touching internals: Collider/MutableCollider with checked revisions, immutable ColliderSnapshot values (SolidColliderSnapshot, RayColliderSnapshot, CompoundColliderSnapshot), mutable AABB, sphere, oriented-box, capsule, ray and compound colliders whose setters validate first and publish atomically, the finite Ray3d value, and the unified entry ColliderQueries.intersects(...). A compound is editable at run time and owns its children as immutable snapshots, so mutating a source collider cannot change a parent without an explicit republication; deep trees are traversed iteratively, so a caller cannot overflow the stack. Placement arithmetic stays inside the frozen geometry package.
EntityColliderHolder, EntityColliderSnapshot, EntityColliders and EntityColliderFrames mirror the entity capability for these general colliders (rays and compounds included), and EntityColliderUpdateEvent plus EntityColliders.requestUpdate(entity, reason) let a consumer recompute shapes from its own state on the owning logical thread; a listener publishes the new snapshot itself. Collision queries stay pure: no events, no damage, no world access, and no allocation on the plain-leaf path. An independent consumer example and its cross-project compile check ship under src/example and tools/.
A client-only F3+B overlay draws cached colliders as real outlines — oriented boxes from their own axes, sphere and capsule circles at the correct radius, rays at their true finite length — and reads the vanilla debug toggle, doing no geometry work while it is off. It lives in dev.crlhitbox.internal.client; common and server classes hold no client linkage.
Six absolute throughput benchmarks for the collider entry points ship in an isolated src/jmh source set with a frozen protocol and a threshold checker. The current candidate meets one of the six targets (P02 capsulePair); the others are short and are recorded, with corrected-input numbers, in docs/COLLIDER_BENCHMARK_PROTOCOL.md. An earlier "three of six" reading came from a benchmark data set in which every prepared pair was in fact separated, so no query ran its real narrow phase; that reading is withdrawn and the inputs are now asserted at setup. No JMH type reaches the shipped artifact.
Entity hitbox state is replicated by a versioned, direct-binary, server-authoritative full-snapshot protocol documented in docs/FULL_SNAPSHOT_PROTOCOL.md: one crlhitbox channel, one client-bound message, frozen shape tags and limits, strict bounded VarInt coding, exact round trips checked against an independently written oracle, provider generations, internal replica state, EntityHitboxSync.sendFullTo/sendFullToTrackingAndSelf, automatic delivery when a player starts tracking an Entity and on player login/respawn/dimension change, client-main-thread installation with stale-generation/revision rejection, and a bounded client pending store. Mutating a holder never sends a packet: an already-tracked Entity requires an explicit resend. There is no client-to-server path, no delta packet, no resync request, and no persistence. Automated gates pass, but no dedicated-server run and no real-GPU client run have been performed, so live network replication is not claimed.
Automatic entity-to-world pose extraction beyond the translation-only display frame, delta packets, client resync requests, acknowledgements, persistence, clone or respawn copying, gameplay rendering beyond the debug overlay, combat, hit/hurt roles, model/bone attachment, generic distances, hit-leaf or hit-path results, solid metadata, collision manifolds, penetration depth, contact normals, time of impact, swept or continuous queries, certified geometry, and other platform integration remain deferred. The sealed solid set does not admit third-party implementations in this phase. This library does not claim to replace Minecraft physics.
The finalized project identity is Maven group and Java base package dev.crlhitbox, main class dev.crlhitbox.CrlHitbox, and initial development version 0.1.0-SNAPSHOT. Authors, project URLs, issue tracker, and distribution license remain unresolved.
License decision pending; no distribution license granted by repository metadata. The collision feature set is aligned with HitboxAPI's public README and interfaces, which are a read-only functional reference; see docs/HITBOXAPI_PARITY.md and the authoritative handover plan in docs/CRL_HITBOX_ROADMAP.md.