An original thought

- Require embeddings to specify an origin coordinate on creation

common/src/api/java/dev/engine_room/flywheel/api/visualization/VisualEmbedding.java

@@ -5,6 +5,15 @@ import org.joml.Matrix4fc;
 
 import dev.engine_room.flywheel.api.backend.BackendImplemented;
 
+/**
+ * A visualization context that can apply a transformation to instances created through its instancer provider.
+ *
+ * <p>This is intended to be used for large meta-visuals that may be composed of many block entities or entities.
+ * Invoking a visualizer with a VisualEmbedding will create a "subvisual". The parent visual is responsible for managing
+ * the lifecycle of subvisuals: deleting them, and optionally invoking their frame and tick plans. Subvisuals exist in
+ * the real world from their perspective, and in general visuals should not care if they are within a VisualEmbedding.
+ * However, if a visual wants to check it can use {@code instanceof VisualEmbedding} on its VisualizationContext.</p>
+ */
 @BackendImplemented
 public interface VisualEmbedding extends VisualizationContext {
 	/**

common/src/api/java/dev/engine_room/flywheel/api/visualization/VisualizationContext.java

@@ -17,9 +17,23 @@ public interface VisualizationContext {
 	/**
 	 * All models render as if this position is (0, 0, 0).
 	 *
+	 * <p>For a Visual to appear in the correct position in the world,
+	 * it must render at its actual world position minus this renderOrigin.
+	 * <br>i.e. {@code be.getBlockPos() - visualizationContext.renderOrigin()}</p>
+	 *
+	 * <p>This exists to prevent floating point precision issues
+	 * when the camera is far away from the level's origin.</p>
+	 *
 	 * @return The origin of the renderer as a level position.
 	 */
 	Vec3i renderOrigin();
 
-	VisualEmbedding createEmbedding();
+	/**
+	 * Create a new embedding to compose visuals.
+	 *
+	 * @param renderOrigin The renderOrigin the embedding will appear to have.
+	 * @return The embedding.
+	 * @see VisualEmbedding
+	 */
+	VisualEmbedding createEmbedding(Vec3i renderOrigin);
 }

common/src/backend/java/dev/engine_room/flywheel/backend/engine/EngineImpl.java

@@ -141,8 +141,8 @@ public class EngineImpl implements Engine {
 		}
 
 		@Override
-		public VisualEmbedding createEmbedding() {
-			var out = new EmbeddedEnvironment(EngineImpl.this, visualType);
+		public VisualEmbedding createEmbedding(Vec3i renderOrigin) {
+			var out = new EmbeddedEnvironment(EngineImpl.this, visualType, renderOrigin);
 			environmentStorage.track(out);
 			return out;
 		}

common/src/backend/java/dev/engine_room/flywheel/backend/engine/embed/EmbeddedEnvironment.java

@@ -21,6 +21,7 @@ import net.minecraft.core.Vec3i;
 public class EmbeddedEnvironment implements VisualEmbedding, Environment {
 	private final EngineImpl engine;
 	private final VisualType visualType;
+	private final Vec3i renderOrigin;
 	@Nullable
 	private final EmbeddedEnvironment parent;
 	private final InstancerProvider instancerProvider;
@@ -32,9 +33,10 @@ public class EmbeddedEnvironment implements VisualEmbedding, Environment {
 
 	private boolean deleted = false;
 
-	public EmbeddedEnvironment(EngineImpl engine, VisualType visualType, @Nullable EmbeddedEnvironment parent) {
+	public EmbeddedEnvironment(EngineImpl engine, VisualType visualType, Vec3i renderOrigin, @Nullable EmbeddedEnvironment parent) {
 		this.engine = engine;
 		this.visualType = visualType;
+		this.renderOrigin = renderOrigin;
 		this.parent = parent;
 
 		instancerProvider = new InstancerProvider() {
@@ -46,8 +48,8 @@ public class EmbeddedEnvironment implements VisualEmbedding, Environment {
 		};
 	}
 
-	public EmbeddedEnvironment(EngineImpl engine, VisualType visualType) {
-		this(engine, visualType, null);
+	public EmbeddedEnvironment(EngineImpl engine, VisualType visualType, Vec3i renderOrigin) {
+		this(engine, visualType, renderOrigin, null);
 	}
 
 	@Override
@@ -63,12 +65,12 @@ public class EmbeddedEnvironment implements VisualEmbedding, Environment {
 
 	@Override
 	public Vec3i renderOrigin() {
-		return Vec3i.ZERO;
+		return renderOrigin;
 	}
 
 	@Override
-	public VisualEmbedding createEmbedding() {
-		var out = new EmbeddedEnvironment(engine, visualType, this);
+	public VisualEmbedding createEmbedding(Vec3i renderOrigin) {
+		var out = new EmbeddedEnvironment(engine, visualType, renderOrigin, this);
 		engine.environmentStorage()
 				.track(out);
 		return out;