add IDhApiLevelWrapper.getBlockColorPreApi()

api/src/main/java/com/seibel/distanthorizons/api/interfaces/world/IDhApiLevelWrapper.java

@@ -21,8 +21,14 @@ package com.seibel.distanthorizons.api.interfaces.world;
 
 import com.seibel.distanthorizons.api.interfaces.IDhApiUnsafeWrapper;
 import com.seibel.distanthorizons.api.enums.worldGeneration.EDhApiLevelType;
+import com.seibel.distanthorizons.api.interfaces.block.IDhApiBiomeWrapper;
+import com.seibel.distanthorizons.api.interfaces.block.IDhApiBlockStateWrapper;
 import com.seibel.distanthorizons.api.interfaces.render.IDhApiCustomRenderRegister;
+import com.seibel.distanthorizons.api.methods.events.abstractEvents.DhApiBlockColorOverrideEvent;
+import com.seibel.distanthorizons.api.objects.DhApiResult;
+import com.seibel.distanthorizons.api.objects.data.IDhApiFullDataSource;
 
+import java.awt.*;
 import java.io.File;
 
 /**
@@ -90,6 +96,26 @@ public interface IDhApiLevelWrapper extends IDhApiUnsafeWrapper
 	 */
 	File getDhSaveFolder();
 	
+	/**
+	 * Returns the color DH would use for the given block/biome
+	 * pair at the given world position before any API color overrides
+	 * are considered. <br>
+	 * API color overrides are ignored to prevent infinite
+	 * loops if this event is triggered inside said API override.
+	 * <br><br>
+	 * 
+	 * Returns {@link DhApiResult#success} = false if {@link IDhApiLevelWrapper#getLevelType()} returns a {@link EDhApiLevelType#SERVER_LEVEL}
+	 * (server levels have no concept of textures or colors).
+	 * 
+	 * @see DhApiBlockColorOverrideEvent
+	 * @since API 7.0.0
+	 */
+	DhApiResult<Color> getBlockColorPreApi(
+		IDhApiBlockStateWrapper blockStateWrapper,
+		IDhApiBiomeWrapper biomeWrapper,
+		int blockWorldPosX, int blockWorldPosY, int blockWorldPosZ,
+		IDhApiFullDataSource dataSource);
+	
 	
 	
 }

api/src/main/java/com/seibel/distanthorizons/api/methods/events/abstractEvents/DhApiBlockColorOverrideEvent.java

@@ -19,16 +19,21 @@
 
 package com.seibel.distanthorizons.api.methods.events.abstractEvents;
 
+import com.seibel.distanthorizons.api.interfaces.block.IDhApiBiomeWrapper;
 import com.seibel.distanthorizons.api.interfaces.block.IDhApiBlockStateWrapper;
 import com.seibel.distanthorizons.api.interfaces.world.IDhApiLevelWrapper;
 import com.seibel.distanthorizons.api.methods.events.interfaces.IDhApiEvent;
 import com.seibel.distanthorizons.api.methods.events.interfaces.IDhApiEventParam;
 import com.seibel.distanthorizons.api.methods.events.sharedParameterObjects.DhApiEventParam;
+import com.seibel.distanthorizons.api.objects.data.IDhApiFullDataSource;
 import com.seibel.distanthorizons.coreapi.util.ColorUtil;
 
 /**
- * Performance note: this event will be fired thousands of times on concurrent threads, 
- * make it thread safe and as fast as possible. <Br><Br>
+ * Performance note: this event will be fired millions of times on concurrent threads, 
+ * make it thread safe and as fast as possible. <br> 
+ * (If every LOD block goes through this event, On a 512 render distance world, 
+ * at the medium quality preset, it will be triggered around 40,000,000 times.)
+ * <Br><Br>
  * 
  * This event is fired when DH needs to convert a {@link IDhApiBlockStateWrapper}
  * into a color for rendering. This event is fired after DH attempts to determine
@@ -41,7 +46,7 @@ import com.seibel.distanthorizons.coreapi.util.ColorUtil;
  * via {@link DhApiBlockStateWrapperCreatedEvent.EventParam#setAllowApiColorOverride(boolean)}.
  * 
  * @author James Seibel
- * @version 2026-04-14
+ * @version 2026-05-18
  * @since API 6.0.0
  * @see IDhApiBlockStateWrapper
  */
@@ -50,6 +55,7 @@ public abstract class DhApiBlockColorOverrideEvent implements IDhApiEvent<DhApiB
 	public abstract void onBlockColorOverridden(DhApiEventParam<EventParam> event);
 	
 	
+	
 	//=========================//
 	// internal DH API methods //
 	//=========================//
@@ -58,6 +64,7 @@ public abstract class DhApiBlockColorOverrideEvent implements IDhApiEvent<DhApiB
 	public final void fireEvent(DhApiEventParam<EventParam> event) { this.onBlockColorOverridden(event); }
 	
 	
+	
 	//==================//
 	// parameter object //
 	//==================//
@@ -65,7 +72,9 @@ public abstract class DhApiBlockColorOverrideEvent implements IDhApiEvent<DhApiB
 	public static class EventParam implements IDhApiEventParam
 	{
 		private IDhApiLevelWrapper levelWrapper;
+		private IDhApiFullDataSource dataSource;
 		private IDhApiBlockStateWrapper blockStateWrapper = null;
+		private IDhApiBiomeWrapper biomeWrapper = null;
 		private int colorAsInt = -1;
 		private int blockPosX = 0, blockPosY = 0, blockPosZ = 0;
 		
@@ -74,17 +83,22 @@ public abstract class DhApiBlockColorOverrideEvent implements IDhApiEvent<DhApiB
 		//=============//
 		// constructor //
 		//=============//
+		//region
 		
 		public EventParam() {}
 		
 		public void update(
 			IDhApiLevelWrapper levelWrapper,
-			IDhApiBlockStateWrapper blockStateWrapper, 
+			IDhApiFullDataSource dataSource,
+			IDhApiBlockStateWrapper blockStateWrapper,
+			IDhApiBiomeWrapper biomeWrapper,
 			int colorAsInt,
 			int blockPosX, int blockPosY, int blockPosZ)
 		{
 			this.levelWrapper = levelWrapper;
+			this.dataSource = dataSource;
 			this.blockStateWrapper = blockStateWrapper;
+			this.biomeWrapper = biomeWrapper;
 			this.colorAsInt = colorAsInt;
 			
 			this.blockPosX = blockPosX;
@@ -92,15 +106,27 @@ public abstract class DhApiBlockColorOverrideEvent implements IDhApiEvent<DhApiB
 			this.blockPosZ = blockPosZ;
 		}
 		
+		//endregion
+		
 		
 		
 		//=================//
 		// getters/setters //
 		//=================//
+		//region
 		
 		public IDhApiBlockStateWrapper getBlockStateWrapper() { return this.blockStateWrapper; }
+		/** @since API 7.0.0 */
+		public IDhApiBiomeWrapper getBiomeWrapper() { return this.biomeWrapper; }
 		
-		public IDhApiLevelWrapper getLevelWrapper() { return levelWrapper; }
+		/** the level DH is resolving this block's color in. */
+		public IDhApiLevelWrapper getLevelWrapper() { return this.levelWrapper; }
+		/** 
+		 * The DH datasource that contains this block's position. Can be used to access adjacent
+		 * {@link IDhApiBlockStateWrapper}'s and {@link IDhApiBiomeWrapper}'s for adjacent aware tinting.
+		 * @since API 7.0.0
+		 */
+		public IDhApiFullDataSource getDataSource() { return this.dataSource; }
 		
 		public int getColorAsInt() { return this.colorAsInt; }
 		public int getAlpha() { return ColorUtil.getAlpha(this.colorAsInt); }
@@ -130,8 +156,15 @@ public abstract class DhApiBlockColorOverrideEvent implements IDhApiEvent<DhApiB
 		/** @return the block's Z value in the world */
 		public int getBlockPosZ() { return blockPosZ; }
 		
+		//endregion
 		
 		
+		
+		//==========================//
+		// base api event overrides //
+		//==========================//
+		//region
+		
 		/** 
 		 * Returns the same instance of this event.
 		 * Copying this event isn't supported
@@ -145,6 +178,8 @@ public abstract class DhApiBlockColorOverrideEvent implements IDhApiEvent<DhApiB
 		@Override 
 		public boolean getCopyBeforeFire() { return false; }
 		
+		//endregion
+		
 		
 		
 	}

api/src/main/java/com/seibel/distanthorizons/api/objects/DhApiResult.java

@@ -46,7 +46,7 @@ public class DhApiResult<T>
 	
 	
 	
-	// these constructors are private because the create... methods below are easier to understand
+	// these constructors are private because the create methods below are easier to understand
 	private DhApiResult(boolean success, String message) { this(success, message, null); }
 	private DhApiResult(boolean success, String message, T payload)
 	{