LambDynamicLights

https://lambdaurora.dev/projects/lambdynamiclights/docs/v4/
Admin
LambDynamicLights is a Minecraft mod that provides data-driven and Java-based APIs to make items or...
Tokens:5,303
Snippets:60
Trust Score:7.2
Update:2 months ago
Show doc for...
Tokens:
Raw
### Define Item Lighting via JSON

Source: https://lambdaurora.dev/projects/lambdynamiclights/docs/v4/item.html

Examples of item lighting configuration files for various Minecraft items.

```json
{
	"match": {
		"items": "minecraft:fire_charge"
	},
	"luminance": 10,
	"water_sensitive": true
}
```

```json
{
	"match": {
		"items": "minecraft:lava_bucket"
	},
	"luminance": {
		"type": "block",
		"block": "minecraft:lava"
	},
	"water_sensitive": true
}
```

```json
{
	"match": {
		"items": "minecraft:nether_star"
	},
	"luminance": 8
}
```

```json
{
	"match": {
		"items": [
			"minecraft:torch",
			"minecraft:redstone_torch",
			"minecraft:soul_torch"
		]
	},
	"luminance": {
		"type": "block_self"
	},
	"water_sensitive": true
}
```

--------------------------------

### Match Entity Types

Source: https://lambdaurora.dev/projects/lambdynamiclights/docs/v4/entity.html

Examples for matching single, multiple, or tagged entity types within the configuration.

```json
"type": "minecraft:blaze"
```

```json
"type": [
	"minecraft:blaze",
	"minecraft:magma_cube",
	"#minecraft:zombies"
]
```

```json
"type": "#minecraft:skeletons"
```

--------------------------------

### Configure NeoForge or common source set dependencies

Source: https://lambdaurora.dev/projects/lambdynamiclights/docs/v4

Setup dependencies with specific mapping attributes for NeoForge or common project structures.

```gradle
val mappingsAttribute = Attribute.of("net.minecraft.mappings", String::class)

dependencies {
	attributesSchema {
		attribute(mappingsAttribute)
	}

	// The API of LambDynamicLights.
	// This is only required for compilation if you're using the Java API.
	compileOnly("dev.lambdaurora.lambdynamiclights:lambdynamiclights-api:<version>") {
		attributes {
			attribute(mappingsAttribute, "mojmap")
		}
	}

	// For runtime of LambDynamicLights.
	// Include only if you need to test in your dev env compatibility with LambDynamicLights.
	// Replace with runtimeOnly if you want the dependency to be transitive.
	localRuntime("dev.lambdaurora.lambdynamiclights:lambdynamiclights-runtime:<version>") {
		attributes {
			attribute(mappingsAttribute, "mojmap")
		}
	}
}
```

--------------------------------

### JSON Configuration for Entity Luminance

Source: https://lambdaurora.dev/projects/lambdynamiclights/docs/v4/java.html

Example JSON structure to apply the registered custom luminance provider.

```json
{
	"type": "<your namespace>:custom",
	"invert": false
}
```

--------------------------------

### Create a Dynamic Lights Initializer

Source: https://lambdaurora.dev/projects/lambdynamiclights/docs/v4/java.html

Implement the DynamicLightsInitializer interface to define custom dynamic lighting logic.

```java
public class YourModDynamicLightsInitializer implements DynamicLightsInitializer {
	@Override
	void onInitializeDynamicLights(
		DynamicLightsContext context
	) {
		// Code related to dynamic lighting here.
	}
}
```

--------------------------------

### Register Item and Entity Lighting via Java

Source: https://lambdaurora.dev/projects/lambdynamiclights/docs/v4/java.html

Register custom lighting data for items and entities using the onRegisterEvent listener pattern.

```java
context.itemLightSourceManager().onRegisterEvent().register(context -> {
	// You have registry access through context.registryAccess()
	
	// Register item lighting with any of the context.register() overloads.
	context.register(Items.ALLIUM, 5);
});

context.entityLightSourceManager().onRegisterEvent().register(context -> {
	// You have registry access through context.registryAccess()
	
	// Register entity lighting with any of the context.register() overloads.
	context.register(EntityType.ARMADILLO,
		new ItemDerivedEntityLuminance(
			new ItemStack(Items.TORCH),
			/* include rain? */ false,
			Optional.empty()
		)
	);
});
```

--------------------------------

### Create a Fade-Out Dynamic Light Behavior

Source: https://lambdaurora.dev/projects/lambdynamiclights/docs/v4/java.html

Implements a light source that persists for 600 ticks and gradually decreases in luminance.

```java
public class FadeOutDynamicLightBehavior implements DynamicLightBehavior {
	private final double x;
	private final double y;
	private final double z;
	private final BoundingBox box;
	private int remainingTicks = 600;
	private int lastLuminance = 15;
	private int luminance = 15;

	public FadeOutDynamicLightBehavior(BlockPos pos) {
		this.x = pos.getX() + 0.5;
		this.y = pos.getY() + 0.5;
		this.z = pos.getZ() + 0.5;

		this.box = new BoundingBox(
				pos.getX(), pos.getX() + 1,
				pos.getY(), pos.getY() + 1,
				pos.getZ(), pos.getZ() + 1
		);
	}

	@Override
	public @Range(from = 0, to = 15) double lightAtPos(BlockPos pos, double falloffRatio) {
		double dx = pos.getX() - this.x + 0.5;
		double dy = pos.getY() - this.y + 0.5;
		double dz = pos.getZ() - this.z + 0.5;

		double distanceSquared = dx * dx + dy * dy + dz * dz;
		return Math.max(
				this.luminance - Math.sqrt(distanceSquared) * falloffRatio,
				0.0
		);
	}

	@Override
	public @NotNull BoundingBox getBoundingBox() {
		return this.box;
	}

	@Override
	public boolean hasChanged() {
		if (this.luminance != this.lastLuminance) {
			this.lastLuminance = this.luminance;
			return true;
		} else {
			return false;
		}
	}

	public void tick() {
		// Function called every tick somewhere.
		this.luminance = (int) (remainingTicks / 600.f * 15.f);
		this.remainingTicks--;
	}

	@Override
	public boolean isRemoved() {
		return this.remainingTicks == 0;
	}
}
```

--------------------------------

### Implement a Singleton Entity Luminance Provider

Source: https://lambdaurora.dev/projects/lambdynamiclights/docs/v4/java.html

Defines a simple singleton luminance provider that does not require a Codec.

```java
public final class ConstantEntityLuminance implements EntityLuminance {
	// The singleton instance.
	public static final ConstantEntityLuminance INSTANCE = new ConstantEntityLuminance();

	private ConstantEntityLuminance() {}

	@Override
	public Type type() {
		// This is the registered type of this entity luminance provider.
		return YourModDynamicLightsInitializer.CONSTANT;
	}

	@Override
	public @Range(from = 0, to = 15) int getLuminance(
		ItemLightSourceManager itemLightSourceManager,
		Entity entity
	) {
		return 5;
	}
}

// And in your initializer file:
public class YourModDynamicLightsInitializer implements DynamicLightsInitializer {

	public static final EntityLuminance.Type CONSTANT
		= EntityLuminance.Type.registerSimple(
			Identifier.of("<your namespace>", "custom"),
			ConstantEntityLuminance.INSTANCE
		);

	// Initializer code
}
```

--------------------------------

### Register Initializer in NeoForge

Source: https://lambdaurora.dev/projects/lambdynamiclights/docs/v4/java.html

Add the initializer to the modproperties table in the neoforge.mods.toml file.

```toml
[[mods]]
# Stuff

[modproperties."${mod_id}"."yumi:entrypoints"]
	"lambdynlights:initializer" = "<package>.YourModDynamicLightsInitializer"
```

--------------------------------

### Configure Fabric dependencies

Source: https://lambdaurora.dev/projects/lambdynamiclights/docs/v4

Add the API for compilation and the runtime for testing in a Fabric development environment.

```gradle
dependencies {
	// The API of LambDynamicLights.
	// This is only required for compilation if you're using the Java API.
	modCompileOnly("dev.lambdaurora.lambdynamiclights:lambdynamiclights-api:<version>")

	// For runtime of LambDynamicLights.
	// Include only if you need to test in your dev env compatibility with LambDynamicLights.
	// Replace with modRuntimeOnly if you want the dependency to be transitive.
	modLocalRuntime("dev.lambdaurora.lambdynamiclights:lambdynamiclights-runtime:<version>")
}
```

--------------------------------

### DynamicLightBehavior Interface

Source: https://lambdaurora.dev/projects/lambdynamiclights/docs/v4/java.html

The interface to implement for creating custom dynamic light behaviors. It defines how light is calculated, the bounding box of the light, and its lifecycle.

```APIDOC
## Interface: DynamicLightBehavior

### Methods

- **double lightAtPos(BlockPos pos, double falloffRatio)**: Calculates the light level at a given position within the bounding box. The `falloffRatio` is used to scale distance calculations.
- **BoundingBox getBoundingBox()**: Returns the current bounding box of the dynamic light behavior.
- **boolean hasChanged()**: Returns true if the behavior needs to be updated (e.g., light level or position change).
- **boolean isRemoved()**: Returns true if the behavior should be discarded by the system.
```

--------------------------------

### Register Lighting Sources

Source: https://lambdaurora.dev/projects/lambdynamiclights/docs/v4/java.html

Methods to register custom item or entity lighting sources via Java events.

```APIDOC
## Register Lighting Sources

### Description
Register custom lighting data for items or entities using the registration event listeners.

### Methods
- `itemLightSourceManager().onRegisterEvent().register(consumer)`: Registers a listener to define item lighting.
- `entityLightSourceManager().onRegisterEvent().register(consumer)`: Registers a listener to define entity lighting.

### Usage
Use `context.register(Item, int)` for items or `context.register(EntityType, EntityLuminance)` for entities within the registration callback.
```

--------------------------------

### Add Maven repository for LambDynamicLights

Source: https://lambdaurora.dev/projects/lambdynamiclights/docs/v4

Include this repository in your buildscript to access the LambDynamicLights artifacts.

```gradle
repositories {
	maven {
		name = "Gegy"
		url = uri("https://maven.gegy.dev")
	}
}
```

--------------------------------

### Register Initializer in Fabric

Source: https://lambdaurora.dev/projects/lambdynamiclights/docs/v4/java.html

Add the initializer to the entrypoints field in the fabric.mod.json file.

```json
	"entrypoints": {
		"lambdynlights:initializer": [
			"<package>.YourModDynamicLightsInitializer"
		]
	}
```

--------------------------------

### Configure Item Frame Dynamic Lights

Source: https://lambdaurora.dev/projects/lambdynamiclights/docs/v4/entity.html

Defines luminance behavior for standard and glow item frames using the item_frame handler or static values.

```json
{
	"match": {
		"type": [
			"minecraft:item_frame",
			"minecraft:glow_item_frame"
		]
	},
	"luminance": {
		"type": "lambdynlights:item_frame"
	}
}
```

```json
{
	"match": {
		"type": "minecraft:glow_item_frame"
	},
	"luminance": 12
}
```

--------------------------------

### Query Dynamic Light Values

Source: https://lambdaurora.dev/projects/lambdynamiclights/docs/v4/java.html

Use the item and entity light source managers to retrieve the current luminance value for specific items or entities.

```java
int lightOfTorch = context.itemLightSourceManager().getLuminance(
		new ItemStack(Items.TORCH), 
		/* submerged in water */ false
	);

Entity cow = /* get a cow */;
int lightOfCow = context.entityLightSourceManager().getLuminance(cow);
```

--------------------------------

### Implement a Custom Entity Luminance Provider

Source: https://lambdaurora.dev/projects/lambdynamiclights/docs/v4/java.html

Defines a record implementing EntityLuminance with a MapCodec for JSON parsing and custom luminance logic.

```java
public record CustomEntityLuminance(boolean invert) implements EntityLuminance {
	// The Codec of this entity luminance provider,
	// this describes how to parse the JSON file.
	public static final MapCodec<CustomEntityLuminance> CODEC = RecordCodecBuilder.mapCodec(
			instance -> instance.group(
				Codec.BOOL.fieldOf("invert").forGetter(CustomEntityLuminance::invert)
			).apply(instance, CustomEntityLuminance::new)
	);

	@Override
	public Type type() {
		// This is the registered type of this entity luminance provider.
		// We will modify the initializer to reflect this.
		return YourModDynamicLightsInitializer.CUSTOM_ENTITY_LUMINANCE;
	}

	@Override
	public @Range(from = 0, to = 15) int getLuminance(
		ItemLightSourceManager itemLightSourceManager,
		Entity entity
	) {
		// Here we compute the luminance the given entity should emit.
		// We also have access to the item light source manager,
		// in case our luminance depends on the luminance of an item.
		boolean isNight = this.invert ? entity.level().isDay() : entity.level().isNight();

		return isNight ? 10 : 0;
	}
}
```

--------------------------------

### Configure Allay Dynamic Light

Source: https://lambdaurora.dev/projects/lambdynamiclights/docs/v4/entity.html

Sets a static luminance value of 8 for the Allay entity.

```json
{
	"match": {
		"type": "minecraft:allay"
	},
	"luminance": 8
}
```

--------------------------------

### Configure Blaze Dynamic Light

Source: https://lambdaurora.dev/projects/lambdynamiclights/docs/v4/entity.html

Uses a wet-sensitive luminance type to adjust light levels based on whether the Blaze is wet or dry.

```json
{
	"match": {
		"type": "minecraft:blaze"
	},
	"luminance": {
		"type": "lambdynlights:wet_sensitive",
		"dry": 10,
		"wet": 4
	}
}
```

--------------------------------

### DynamicLightBehaviorManager

Source: https://lambdaurora.dev/projects/lambdynamiclights/docs/v4/java.html

Manager class used to register and remove dynamic light behaviors within the current client world.

```APIDOC
## Class: DynamicLightBehaviorManager

### Methods

- **add(DynamicLightBehavior behavior)**: Adds a new dynamic light behavior to the manager.
- **remove(DynamicLightBehavior behavior)**: Removes an existing dynamic light behavior from the manager.
```

--------------------------------

### Register Entity Luminance in Initializer

Source: https://lambdaurora.dev/projects/lambdynamiclights/docs/v4/java.html

Registers the custom luminance provider type using its Codec within the mod initializer.

```java
public class YourModDynamicLightsInitializer implements DynamicLightsInitializer {

	public static final EntityLuminance.Type CUSTOM_ENTITY_LUMINANCE
		= EntityLuminance.Type.register(
			Identifier.of("<your namespace>", "custom"),
			CustomEntityLuminance.CODEC
		);

	// Initializer code
}
```

--------------------------------

### Query Dynamic Light Values

Source: https://lambdaurora.dev/projects/lambdynamiclights/docs/v4/java.html

Methods to retrieve the current luminance value for specific items or entities using the DynamicLightsContext.

```APIDOC
## Query Dynamic Light Values

### Description
Retrieve the dynamic light value (luminance) for a given ItemStack or Entity.

### Methods
- `itemLightSourceManager().getLuminance(ItemStack stack, boolean submergedInWater)`: Returns the integer luminance value for an item.
- `entityLightSourceManager().getLuminance(Entity entity)`: Returns the integer luminance value for an entity.
```

--------------------------------

### lambdynlights:value

Source: https://lambdaurora.dev/projects/lambdynamiclights/docs/v4/entity.html

Provides a static luminance value between 0 and 15.

```APIDOC
## lambdynlights:value

### Description
Provides a given static luminance value. This luminance provider is implicitly used when a number is provided instead of an object.

### Parameters
- **type** (string) - Required - Must be "lambdynlights:value"
- **value** (integer) - Required - The value of the luminance between 0 and 15 (inclusive)
```

--------------------------------

### lambdynlights:item

Source: https://lambdaurora.dev/projects/lambdynamiclights/docs/v4/entity.html

Provides the luminance value based on a specific item.

```APIDOC
## lambdynlights:item

### Description
Provides the luminance value of the given item.

### Parameters
- **type** (string) - Required - Must be "lambdynlights:item"
- **item** (string) - Required - An item identifier
- **include_rain** (boolean) - Optional - Default: false. True if the wetness check should include rain.
- **always** (string) - Optional - Let the item be always considered 'dry' or 'wet'.
```

--------------------------------

### lambdynlights:display

Source: https://lambdaurora.dev/projects/lambdynamiclights/docs/v4/entity.html

Provides a nested luminance only if the display entity doesn't have an overridden brightness.

```APIDOC
## lambdynlights:display

### Description
Provides a nested luminance only if the display entity doesn't have an overridden brightness.

### Parameters
- **type** (string) - Required - Must be "lambdynlights:display"
- **luminance** (object) - Required - A luminance value or values if the display entity doesn't have an overridden brightness
```

--------------------------------

### lambdynlights:water_sensitive

Source: https://lambdaurora.dev/projects/lambdynamiclights/docs/v4/entity.html

Provides a luminance value depending on whether the entity is out of water or underwater.

```APIDOC
## lambdynlights:water_sensitive

### Description
Provides a luminance value depending on whether the entity is out of water or underwater.

### Parameters
- **type** (string) - Required - Must be "lambdynlights:water_sensitive"
- **out_of_water** (object) - Optional - A luminance value or values if the entity is out of water
- **in_water** (object) - Optional - A luminance value or values if the entity is underwater
```

--------------------------------

### lambdynlights:wet_sensitive

Source: https://lambdaurora.dev/projects/lambdynamiclights/docs/v4/entity.html

Provides the luminance value depending on whether the entity is wet or dry.

```APIDOC
## lambdynlights:wet_sensitive

### Description
Provides the luminance value depending on whether the entity is wet or dry.

### Parameters
- **type** (string) - Required - Must be "lambdynlights:wet_sensitive"
- **dry** (object) - Optional - A luminance value or values if the entity is dry
- **wet** (object) - Optional - A luminance value or values if the entity is wet
```
Tokens:
Raw