Sable Drydock

Sable Drydock

Sable Drydock is an addon for Sable that changes the size of sub-levels: ships, vehicles and other physics structures. A resized structure changes in every respect, not only in appearance. Its rendering, collision, mass, inertia and joints all correspond to the new scale. The mod also provides a sub-level manager with a 3D view, in which sub-levels are inspected, edited, assembled and welded.

Overview

Sable supports scale in its internal representation of a sub-level, but does not apply it to physics, networking or persistence. Sable Drydock completes this support and makes it available through commands and a graphical interface.

Features

Physical scaling

• The physics collider is rebuilt at the new size, so a scaled structure collides with terrain and other structures according to its visible dimensions.
• Mass scales with the cube of the scale factor and inertia with its fifth power. Forces produced by the structure's own engines and propellers scale in the same proportion, so a scaled vehicle keeps its handling characteristics.
• Joints, bearings and other constraints are recalculated for the new size. Structures connected to the resized one are resized together with it.
• Entities can stand on, walk across and interact with a scaled structure at its new size.

Non-uniform scale

• A sub-level can be scaled separately along its own X, Y and Z axes. A cube of 3×3×3 blocks can, for example, become a plate of 3×1×3.
• The collider, mass, inertia, joints, entity collision and rendering all follow the resulting shape. Mass scales with the volume.

Transitions

• Resizing is performed as a smooth transition rather than an instant change.
• A structure that grows is lifted clear of the ground instead of intersecting it.
• Pieces separated from a scaled structure keep its scale.

Persistence and synchronisation

• Scales are saved with the world and restored on load.
• Scale changes are synchronised to every connected player.

Mass and center of mass

• The mass of a sub-level can be set in kilograms. A set mass remains unchanged when blocks are added or removed and when the sub-level is resized. Clearing it restores the mass calculated from the blocks.
• The center of mass can be moved anywhere within the sub-level's bounds. Inertia is recalculated accordingly.
• Both values are saved with the world.

Sub-level manager

• A configurable key (K by default) opens the manager; by default only operators may use it. It lists all sub-levels in every dimension, with welded and connected ones grouped, and shows the selected one in a large 3D view. Sub-levels saved on disk but not loaded are listed and marked as such; the sub-levels being worked with (selected, in the view, in the assembly dock) are loaded when needed and kept loaded, without disturbing chunks forced by other means. The list supports search, sorting by distance, name, mass or size, favorites and hidden entries.
• Actions on a sub-level or its whole group: go to, bring to the player, go to its plot, freeze, guard, rename, disassemble, delete, delete the group. Hard delete removes a sub-level and writes the deletion into Sable's saved sub-level files at once, so the sub-level cannot return after an unexpected shutdown.
• Rows can be checked for actions on many sub-levels at once: freeze, guard, hide (each also undoes its flag), delete and hard delete. Checked blueprint and schematic files can be deleted together.
• The 3D view shows a scene: the sub-level selected in the list with its group, and any number of sub-levels brought in by dragging or Ctrl-clicking their rows. The scene remains the same in every tool until it is cleared.
• The camera orbits by left drag, pans by right drag and zooms by the wheel. It also flies like the camera of a 3D editor: W A S D move, Q and E go down and up, Shift is faster, and holding Alt turns it with the mouse as in game. The wheel changes the flying speed while a movement key or Alt is held. The camera stays where it is when sub-levels are added or resized; Reset view fits the whole scene. A card in the corner of the view lists the controls.
• Editing tools in the 3D view: scale and proportions are typed or set by dragging a corner of the sub-level's box; mass is typed; the center of mass is moved with X, Y and Z arrows or entered as an offset. Changes take effect when Apply is pressed, on every selected sub-level at once, and every part a new scale reaches is previewed at its new size.
• A click selects one part; Ctrl- or Shift-click adds parts, and a Ctrl- or Shift-drag selects the parts within a box. A group row selects the whole group, which is then resized as one body, so its parts keep their places and welds. A single part of a group takes along only what is welded onto it. Selected parts can be shown alone or hidden in the view.
• Sable Photomancy blueprints and Create schematics can be previewed in the same view.
• The action bar below the view can be hidden. The manager keeps its state, including unfinished assembly work, while it is closed, until the player leaves the world.

Assembly dock

• The weld tool turns the 3D view into a dock. It holds the selected sub-level with its group, sub-levels dragged in from the list (with their groups) and Sable Photomancy blueprints or Create schematics dragged in from their tabs. A dock can also hold only files, or start empty.
• The selected part moves with its group by arrows (or the arrow keys and Page Up/Down: 1 block, Shift 1/16, Ctrl 0.001) and turns by three rings (15°, Shift 1°, Ctrl 0.1°), along the dock's axes, which stay put while parts turn, or along its own axes or those of the other part. The camera turns freely in the dock.
• Points are set on block faces or box corners. A selected point moves anywhere within its part, from block to block; the block it is in is outlined and its coordinates within that block are shown in world blocks, taking the part's scale into account. Snap brings one part onto the other, keeping its rotation or squaring it to the other part.
• Parts are joined through Synaxis: rigidly, by a hinge or by a ball joint. The axis of a hinge is given by two points on each part, and Snap aligns the two axes. Selected parts can be kept from colliding with each other, so a hinge can turn freely; such parts are marked with a dashed outline in the dock and in the list. Collisions with the ground and everything else remain. Existing welds are shown and can be removed.
• A welded or hinged part can be moved to another place without unwelding it first. Loosen lets a weld go in the dock and keeps its points and kind (rigid, hinge with its axis, ball joint); after the part is moved, Weld makes the same joint again where it is shown. A loosened weld is drawn hollow, with a dashed line to where the moved part's anchor is now. Welding two parts that are already joined replaces their weld, so a joint can also be changed in place, for example from rigid to a hinge.
• Place puts everything into the world as shown, without welding; Weld does the same and then joins the two parts. Parts from files become new sub-levels exactly where they are shown; a dock of files only is placed in front of the player. Parts can be removed from the dock one by one, or the dock can be cleared.
• The panel shows the gap between the points, the rotation relative to the other part and the offset of the moved part, for fitting parts exactly.

Rendering

• Scaled structures are rendered correctly with the vanilla renderer and with Sodium.
• Create components rendered through Flywheel, such as shafts and cogwheels, are drawn at the structure's scale.

Commands

All commands require permission level 2 by default.

Command	Description
/drydock set <scale> [sub_level]	Sets a uniform scale.
/drydock axes <x> <y> <z> [sub_level]	Sets the scale along each axis of the sub-level.
/drydock reset [sub_level]	Restores the original size.
/drydock get [sub_level]	Displays the current scale.
/drydock list	Lists all loaded sub-levels in the dimension, nearest first.
/drydock group, delete, delete_group, freeze, unfreeze, guard, unguard, tp, plot, bring, rename, disassemble, disassemble_anyway	Sub-level management, as in the manager.

The sub_level argument accepts a UUID or an exact sub-level name. Tab completion lists every sub-level in the dimension and marks the one the player is looking at. If the argument is omitted, the command applies to the sub-level the player is looking at.

Integrations

• Sable Cleanup Tools (optional): adds an Edit button to the cleanup screen, which opens the manager with the selected sub-level.
• Sable Photomancy (required): blueprints record the scale, manual mass and center of mass of the sub-levels they contain and the pairs kept from colliding, and restore them on placement. The manager previews blueprints, and the assembly dock places blueprints and Create schematics through Photomancy's own placer.
• Synaxis (required): the weld of the Sable Photomancy honey welder aligns and joins scaled sub-levels according to their scaled size. The assembly dock creates rigid welds, hinges and ball joints through Synaxis.
• Create (optional): Flywheel components are drawn at the structure's scale, and Create schematics can be previewed and placed from the manager.

Without an optional mod (Sable Cleanup Tools, Create), the features that depend on it remain visible but inactive, and using them states which mod is required.

Configuration

Server settings are stored in config/sable_drydock-server.toml.

Setting	Default	Description
minScale	0.0625	Minimum permitted scale (configurable down to 1/64).
maxScale	2	Maximum permitted scale (configurable up to 32).
lookDistance	128	Distance at which a sub-level can be selected by looking at it.
permissionLevel	2	Permission level required to use the commands.
managerPermissionLevel	2	Permission level required to open and use the sub-level manager (2: operators).

The scaledPhysicsLimits section contains safety limits for the physics of scaled sub-levels. Each limit can be enabled or disabled independently:

Limit	Default	Purpose
speedCap	Disabled	Maximum linear speed.
spinCap	Disabled	Maximum angular speed.
stepGuard	Enabled	Maximum speed gained in a single tick. Prevents physics instability without restricting normal thrust.
resizeStepGuard	Enabled	A stricter version of stepGuard, applied while a structure is being resized.
externalImpulseGuard	Enabled	Maximum speed change from a single external impact.

Requirements

• Minecraft 1.21.1
• NeoForge 21.1.248 or later
• Sable 2.0.5 or later

Also required: Sable Photomancy 1.0.1+ and Synaxis 1.5.0+. Optional: Sable Cleanup Tools 0.3.0+, Create.

The mod must be installed on both the server and every client.

Compatibility and safety

The mod modifies parts of Sable's physics and rendering code. If a future version of Sable changes that code, the mod does not crash the game: scaling is disabled, and a message in chat and the log identifies the affected components.

Known limitations

• Scaled structures do not process block-specific collision behaviour. Create belts cannot propel a scaled vehicle, and impacts on bells, TNT and fragile blocks are not handled.
• Commands work only on loaded sub-levels; the manager loads a sub-level before working with it.
• Players and other entities are not resized.
• A manually set mass or center of mass is not inherited by pieces separated from a sub-level.
• The manager's 3D view does not show fluids. Track belts of Tracks Plus may not line up there.

Credits and license

The scaling core is derived from Create: Pocket Sized by misterblusky9, and sub-level disassembly and parts of the block preview are derived from Sable Cleanup Tools by SwigBox. Both are used under the MIT License; the notices are included in LICENSE-THIRD-PARTY.md. The remainder of the mod is All Rights Reserved.

Developed for Sable by RyanHCode.