Terra

https://terra.polydev.org/
Admin
Terra is a modern world generation modding platform for Minecraft that provides a voxel world...
Tokens:47,818
Snippets:729
Trust Score:5.4
Update:3 months ago
Show doc for...
Tokens:
Raw
### Palette Configuration Example

Source: https://terra.polydev.org/config/development/pack-from-scratch/introduction.html

Demonstrates how to structure a palette list with Y-level thresholds.

```yaml
palette:
  - Palette A: 319 # From y319 downwards until next palette down (at y30)
  - Palette B: 30  # From y30 downwards until next palette down (at y10)
  - Palette C: 10  # From y10 downwards
```

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

### Standard Config Documentation Example

Source: https://terra.polydev.org/config/documentation/index.html

Template for documenting required and optional parameters in a configuration file.

```yaml
<required-parameter>: ... # Object matching the parameter type
<optional-parameter>: ...

```

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

### Example Domain Warp Configuration

Source: https://terra.polydev.org/config/development/noise/configuring.html

A concrete example using Open Simplex 2 for both the sampler and the warp, with an amplitude of 20.

```yaml
type: DOMAIN_WARP
sampler:
  type: OPEN_SIMPLEX_2
  frequency: 0.005
warp:
  type: OPEN_SIMPLEX_2
amplitude: 20
```

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

### Config-Specific Object Documentation Example

Source: https://terra.polydev.org/config/documentation/index.html

Template for documenting configurations that require nested, type-specific objects.

```yaml
example-object:
  object-parameter: A string.

```

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

### Console Output Example

Source: https://terra.polydev.org/config/documentation/terrascript/syntax.html

The expected console output for the conditional while loop.

```text
Number: 0
Number: 1
Number: 2
Number: 3
Number: 4
```

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

### Define a source configuration file

Source: https://terra.polydev.org/config/development/meta-configuration.html

Example of a source file defining a value that can be referenced by other configurations.

```yaml
my:
  value: something
```

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

### Palette Configuration with Sampler

Source: https://terra.polydev.org/config/development/noise/configuring.html

Example of a palette configuration using an OPEN_SIMPLEX_2 sampler to control material distribution.

```yaml
id: DIRTY_GRASS
layers:
  - # Single layer of grass and dirt blocks
    layers: 1
    materials:
      - "minecraft:grass_block": 1
      - "minecraft:coarse_dirt": 1
    sampler:
      type: OPEN_SIMPLEX_2
      frequency: 0.05
  - # Two layers of dirt below the top layer
    layers: 2
    materials: "minecraft:dirt"
  - # Then finally stone
    layers: 1
    materials: "minecraft:stone"
```

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

### Define base configuration file

Source: https://terra.polydev.org/config/development/pack-from-scratch/oceans.html

Initial setup for the base configuration file defining the ID and type.

```yaml
id: BASE
type: BIOME
```

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

### Define a configuration value

Source: https://terra.polydev.org/config/development/meta-configuration.html

Example structure for a configuration file containing a nested value to be referenced.

```yaml
path:
  to:
    config:
      value: example
```

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

### Example Addon Manifest

Source: https://terra.polydev.org/api/concepts/manifest-addons.html

A standard terra.addon.yml file structure defining addon metadata, entry points, and dependencies.

```yaml
schema-version: 1
contributors:
  - Terra contributors
id: super-cool-addon
version: 1.0.3
entrypoints:
  - "com.example.cool.MySuperCoolEntryPoint"
depends:
  cool-addon: "1.2.+"
website:
  issues: https://example.com/issues
  source: https://example.com/
  docs: https://example.com/wiki
license: MIT License
```

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

### FBM Fractalizer Configuration

Source: https://terra.polydev.org/config/development/noise/configuring.html

Examples of configuring the FBM fractalizer, ranging from basic implementation to advanced parameter tuning.

```yaml
type: FBM
sampler:
  type: OPEN_SIMPLEX_2
```

```yaml
type: FBM
sampler:
  type: OPEN_SIMPLEX_2
octaves: 3
lacunarity: 2
gain: 0.75
```

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

### Define Nested Parameters

Source: https://terra.polydev.org/config/development/config-system.html

Example of a configuration using nested keys to define a parameter value.

```YAML
1a:
2  nested:
3    parameter: a parameter value
```

```JSON
1{
2   "a": {
3      "nested": {
4         "parameter": "a parameter value"
5      }
6   }
7}
```

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

### Variable Declaration Examples

Source: https://terra.polydev.org/config/documentation/terrascript/syntax.html

Examples of declaring variables of type num, str, and bool.

```terra
num aNumber = 0; // Declare a num variable called aNumber with value 0.

str example = "hello, world"; // Declare a str variable called example with a value of "hello, world".

bool condition = false; // Declare a boolean variable called condition with a value of false.
```

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

### Configure WHITE_NOISE with salt

Source: https://terra.polydev.org/config/development/noise/configuring.html

Example of adding an optional salt parameter to a WHITE_NOISE sampler configuration.

```yaml
type: WHITE_NOISE
salt: 2321

```

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

### Define a basic TerraScript structure

Source: https://terra.polydev.org/config/development/pack-from-scratch/trees.html

A minimal example of a .tesf file defining a log and leaf block.

```text
1block(0, 0, 0, "minecraft:oak_log", true);
2block(0, 1, 0, "minecraft:oak_leaves", false);
```

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

### Incorrect Pack Manifest Placements

Source: https://terra.polydev.org/config/development/modifying-existing-pack.html

Examples of invalid directory structures that will prevent the pack from loading correctly.

```text
INCORRECT - Terra/packs/custom-pack/folder/pack.yml
```
Terra/
├── packs/
┆   ├── default.zip
    └── custom-pack/
        └── folder/
            ├── pack.yml
            ┆

```
```

```text
INCORRECT - Terra/packs/custom-pack/original-pack.zip
```
Terra/
├── packs/
┆   ├── default.zip
    └── custom-pack/
        └── original-pack.zip

```
```

```text
INCORRECT - Terra/packs/pack.yml
```
Terra/
├── packs/
┆   ├── default.zip
    ├── pack.yml
    ┆

```
```

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

### Extend base configuration in biome

Source: https://terra.polydev.org/config/development/pack-from-scratch/oceans.html

Example of extending the BASE configuration within a specific biome file.

```yaml
id: OCEAN_BIOME
type: BIOME
extends: BASE

vanilla: minecraft:ocean

...

palette:
  - SAND_PALETTE: 319
  - BLOCK:minecraft:bedrock: -61
```

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

### Configure Terrain and Temperature Samplers

Source: https://terra.polydev.org/config/documentation/objects/NoiseSampler.html

Examples of using the IMAGE sampler type for terrain heightmapping and biome temperature distribution.

```yaml
type: LINEAR_HEIGHTMAP
base: 128
scale: 64
sampler:
  type: IMAGE
  image: mountain_heightmap.png
  channel: GRAYSCALE
  frequency: 1
```

```yaml
type: IMAGE
image: grayscale_circles.png
channel: GRAYSCALE
frequency: 1
```

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

### Pack ID Configuration

Source: https://terra.polydev.org/config/development/modifying-existing-pack.html

Examples of valid and invalid pack ID formats in the pack.yml file.

```yaml
id: CUSTOM
```

```yaml
id: custom id
```

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

### Define Pipeline Biome Placeholders

Source: https://terra.polydev.org/config/documentation/objects/PipelineBiome.html

Example of using 'land' and 'ocean' as placeholder biomes within a SAMPLER source configuration.

```yaml
source:
  type: SAMPLER
  biomes:
    - land: 1
    - ocean: 1
  sampler:
    type: OPEN_SIMPLEX_2
```

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

### Define Ocean Biome Configuration

Source: https://terra.polydev.org/config/development/pack-from-scratch/oceans.html

Initial setup for an ocean biome using a custom terrain sampler and palette.

```yaml
 1id: OCEAN_BIOME
 2type: BIOME
 3
 4vanilla: minecraft:ocean
 5
 6terrain:
 7  sampler:
 8    type: EXPRESSION
 9    dimensions: 3
10    expression: -y + 32
11
12  sampler-2d:
13    type: EXPRESSION
14    dimensions: 2
15    expression: (simplex(x, z)+1) * 4
16    samplers:
17      simplex:
18        type: OPEN_SIMPLEX_2
19        dimensions: 2
20        frequency: 0.04
21
22palette:
23  - SAND_PALETTE: 319
24  - BLOCK:minecraft:bedrock: -61
```

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

### Define 2D Sampler in Biome Configuration

Source: https://terra.polydev.org/config/development/pack-from-scratch/terrain.html

Initial setup for a 2D terrain sampler within a biome configuration file.

```yaml
 1id: FIRST_BIOME
 2type: BIOME
 3
 4vanilla: minecraft:plains
 5
 6terrain:
 7  sampler:
 8    type: EXPRESSION
 9    dimensions: 3
10    expression: -y + 64
11
12  sampler-2d:
13    type: EXPRESSION
14    dimensions: 2
15    expression:
16    samplers:
17      simplex:
18        type: OPEN_SIMPLEX_2
19        dimensions: 2
20        frequency: 0.04
21
22...
```

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

### Initialize ExampleEntryPoint

Source: https://terra.polydev.org/api/intro/adding-structure.html

Set up the entry point class with dependency injection and instantiate the structure.

```java
public class ExampleEntryPoint implements AddonInitializer {
    @Inject
    private Logger logger;

    @Inject
    private Platform platform;

    @Inject
    private BaseAddon addon;

    @Override
    public void initialize() {
        logger.info("Hello, World!");

        RegistryKey key = addon.key("EXAMPLE_STRUCTURE");

        ExampleStructure theStructure = new ExampleStructure(platform, key);

        platform.getEventManager()
                .getHandler(FunctionalEventHandler.class)
                .register(addon, ConfigPackPreLoadEvent.class)
                .then(event -> {
                    logger.info("We're loading a config pack!");
                });
    }
}
```

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

### Implement the Addon Entry Point

Source: https://terra.polydev.org/api/intro/creating-simple-addon.html

Create a class implementing AddonInitializer to serve as the initialization point for the addon.

```java
package com.example.addon;

import com.dfsek.terra.addons.manifest.api.AddonInitializer;

public class ExampleEntryPoint implements AddonInitializer {
    @Override
    public void initialize() {

    }
}
```

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

### Initialize Palette Config

Source: https://terra.polydev.org/config/development/pack-from-scratch/palette.html

Create a new palette configuration file with the required ID and type.

```yaml
1id: GRASS_PALETTE
2type: PALETTE
```

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

### Deeply nest YAML maps

Source: https://terra.polydev.org/config/development/config-data.html

Example of multiple levels of indentation for nested maps.

```yaml
qux:
  baz:
    foo: a
    bar: b

```

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

### Define path-format for STITCHED_BITMAP

Source: https://terra.polydev.org/config/documentation/objects/Image.html

Example configuration for the path-format parameter when using the STITCHED_BITMAP image type.

```yaml
path-format: images/stitched-image/my-image-{row}-{column}.png
```

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

### Invalid YAML key assignment

Source: https://terra.polydev.org/config/development/config-data.html

Example of an invalid configuration where two values are assigned to the same key.

```yaml
key: foo
  baz: bar

```

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

### Equivalent Parameter Orderings in pack.yml

Source: https://terra.polydev.org/config/development/pack-from-scratch/introduction.html

Demonstrates that parameter order and whitespace do not affect manifest parsing.

```yaml
1id: YOUR_PACK_ID
2
3version: 0.1.0
```

```yaml
1id: YOUR_PACK_ID
2version: 0.1.0
```

```yaml
1version: 0.1.0
2id: YOUR_PACK_ID
```

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

### Initialize BlockState in Structure

Source: https://terra.polydev.org/api/intro/adding-structure.html

Demonstrates how to retrieve BlockState instances using the Platform's WorldHandle within a structure's generate method.

```java
public class ExampleStructure implements Structure {
    private final Platform platform;

    public ExampleStructure(Platform platform) {
        this.platform = platform;
    }

    @Override
    public boolean generate(Vector3Int location, WritableWorld world, Random random, Rotation rotation) {
        BlockState oakLog = platform.getWorldHandle().createBlockState("minecraft:oak_log[axis=y]");
        BlockState oakLeaves = platform.getWorldHandle().createBlockState("minecraft:oak_leaves[persistent=true]");

        return false;
    }
}
```

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

### Define Ore Feature Configuration

Source: https://terra.polydev.org/config/development/pack-from-scratch/ores.html

Initial setup for a coal ore feature configuration file.

```yaml
1id: COAL_ORE_FEATURE
2type: FEATURE
```

```yaml
 1id: COAL_ORE_FEATURE
 2type: FEATURE
 3
 4distributor:
 5  type: SAMPLER
 6  sampler:
 7    type: POSITIVE_WHITE_NOISE
 8    salt: 1234
 9  threshold: 10 * (1/256)
10#averageCountPerChunk Divide by 16^2 to get % per column
11
12locator:
13  type: GAUSSIAN_RANDOM
14  amount: 1
15  height:
16    min: -64
17    max: 192
18  standard-deviation: (192-(-64))/6
19# Divide distance from min to max by 6 to fit 3 standard deviations
20
21structures:
22  distribution:
23    type: CONSTANT
24  structures: COAL_ORE
```

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

### Define Pack Manifest Parameters

Source: https://terra.polydev.org/config/development/config-system.html

Basic configuration pack manifest defining identity and versioning.

```YAML
1id: COOL_CONFIG_PACK
2version: 1.0.0
3author: Anon Y. Mous
```

```JSON
1{
2   "id": "COOL_CONFIG_PACK",
3   "version": "1.0.0",
4   "author": "Anon Y. Mous"
5}
```

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

### Use comparison operators in if statements

Source: https://terra.polydev.org/config/documentation/terrascript/syntax.html

Examples of using binary comparison operators to control conditional execution.

```terrascript
if(5 > 1) {
    print("condition is true");
}
```

```terrascript
if(randomInt(2) == 0) {
    print("This message prints half the time!");
}
```

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

### Add Sampler and Palette Addons

Source: https://terra.polydev.org/config/development/pack-from-scratch/introduction.html

Include additional addons required for defining samplers and palettes.

```yaml
addons:
  language-yaml: "1.+"
  chunk-generator-noise-3d: "1.+"
  config-noise-function: "1.+"
  palette-block-shortcut: "1.+"
```

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

### Implement AnimalTemplate Configuration

Source: https://terra.polydev.org/config/development/config-system.html

Valid configuration instance for the AnimalTemplate type.

```YAML
1color: grey
2legs: 4
```

```JSON
1{
2   "color": "grey"
3   "legs": 4
4}
```

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

### Extend base configuration in additional biomes

Source: https://terra.polydev.org/config/development/pack-from-scratch/oceans.html

Demonstrates applying the base configuration extension to multiple biome files.

```yaml
id: FIRST_BIOME
type: BIOME
extends: BASE

...
```

```yaml
id: SECOND_BIOME
type: BIOME
extends: BASE

...
```

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

### Initialize feature config

Source: https://terra.polydev.org/config/development/pack-from-scratch/trees.html

Set the basic identity and type for a new feature configuration file.

```yaml
1id: OAK_TREE_FEATURE
2type: FEATURE
```

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

### Access ConfigPack in Event Listener

Source: https://terra.polydev.org/api/intro/adding-structure.html

Retrieve the ConfigPack instance from the event during the pre-load phase.

```java
platform.getEventManager()
        .getHandler(FunctionalEventHandler.class)
        .register(addon, ConfigPackPreLoadEvent.class)
        .then(event -> {
            logger.info("We're loading a config pack!");

            ConfigPack pack = event.getPack();
        });
```

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

### Configure abstract base settings

Source: https://terra.polydev.org/config/development/pack-from-scratch/oceans.html

Sets the abstract flag and defines the ocean palette parameters for inheritance.

```yaml
id: BASE
type: BIOME
abstract: true

ocean:
  palette: BLOCK:minecraft:water
  level: 62
```

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

### Invalid AnimalTemplate Configuration

Source: https://terra.polydev.org/config/development/config-system.html

Example of a configuration that fails validation due to missing required fields and incorrect data types.

```YAML
1legs: two
```

```JSON
1{
2   "legs": "two"
3}
```

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

### Retrieve Structure Registry

Source: https://terra.polydev.org/api/intro/adding-structure.html

Obtain or create the structure registry from the ConfigPack.

```java
platform.getEventManager()
        .getHandler(FunctionalEventHandler.class)
        .register(addon, ConfigPackPreLoadEvent.class)
        .then(event -> {
            logger.info("We're loading a config pack!");

            ConfigPack pack = event.getPack();
            CheckedRegistry<Structure> structureRegistry = pack.getOrCreateRegistry(Structure.class);
        });
```

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

### Create a Feature Configuration

Source: https://terra.polydev.org/api/intro/adding-structure.html

Defines a feature using a sampler, locator, and structure distribution. Requires the generation-stage-feature, config-feature, config-locators, and config-distributors core addons.

```yaml
id: EXAMPLE_FEATURE
type: FEATURE

distributor:
  type: SAMPLER
  sampler:
    type: POSITIVE_WHITE_NOISE
  threshold: 0.03

locator:
  type: PATTERN
  range:
    min: 64
    max: 150
  pattern:
    type: AND
    patterns:
      - type: MATCH_AIR
        offset: 1
      - type: MATCH
        block: "minecraft:grass_block"
        offset: 0

structures:
  distribution:
    type: CELLULAR
    return: CellValue
    frequency: 0.03
  structures: EXAMPLE_STRUCTURE # Your structure!
```

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

### Define Weighted Color Distribution List

Source: https://terra.polydev.org/config/development/noise/use.html

Examples of defining weighted distributions by repeating items or using explicit weight values.

```yaml
colors:
  - Blue
  - Blue
  - Green
  - Yellow
  - Red
```

```yaml
colors:
  - Blue: 2
  - Green: 1
  - Yellow: 1
  - Red: 1
```

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

### Define the pipeline source

Source: https://terra.polydev.org/config/development/pack-from-scratch/pipeline.html

Set the initial biome layout source using a sampler and a weighted list of biomes.

```yaml
 1id: YOUR_PACK_ID
 2
 3...
 4
 5biomes:
 6  type: PIPELINE
 7  resolution: 4
 8  blend:
 9    amplitude: 2
10    sampler:
11      type: OPEN_SIMPLEX_2
12      frequency: 0.1
13  pipeline:
14    source:
15      type: SAMPLER
16      sampler:
17        dimensions: 2
18        type: CONSTANT
19      biomes:
20        - land: 1
```

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

### Representing Complex Data Structures in YAML and JSON

Source: https://terra.polydev.org/config/development/config-data.html

Examples of a shopping list and appointments represented as nested maps and lists in both YAML and JSON formats.

```yaml
 1shopping-list:
 2  - item: 1L Milk
 3    amount: 2
 4    cost-per-item: 2.0
 5  - item: Carton of Eggs
 6    amount: 1
 7    cost-per-item: 4.5
 8
 9appointments:
10  - name: Haircut Appointment
11    date: 24.04.22
12    start-time: 9:45
13    end-time: 10:15
14  - name: Doctor Appointment
15    date: 13.05.22
16    start-time: 3:15
17    end-time: 4:15
```

```json
 1{
 2   "shopping-list": [
 3      {
 4         "item": "1L Milk",
 5         "amount": 2,
 6         "cost-per-item": 2
 7      },
 8      {
 9         "item": "Carton of Eggs",
10         "amount": 1,
11         "cost-per-item": 4.5
12      }
13   ],
14   "appointments": [
15      {
16         "name": "Haircut Appointment",
17         "date": "24.04.22",
18         "start-time": 585,
19         "end-time": 615
20      },
21      {
22         "name": "Doctor Appointment",
23         "date": "13.05.22",
24         "start-time": 195,
25         "end-time": 255
26      }
27   ]
28}
```

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

### Add pipeline blending configuration

Source: https://terra.polydev.org/config/development/pack-from-scratch/pipeline.html

Configure blending using OPEN_SIMPLEX_2 to reduce blocky edges in biome placement.

```yaml
 1id: YOUR_PACK_ID
 2
 3...
 4
 5biomes:
 6  type: PIPELINE
 7  resolution: 4
 8  blend:
 9    amplitude: 2
10    sampler:
11      type: OPEN_SIMPLEX_2
12      frequency: 0.1
```

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

### Using Alternative YAML Inline Syntax

Source: https://terra.polydev.org/config/development/config-data.html

Demonstrates using curly braces and square brackets for maps and lists in YAML to avoid indentation requirements.

```yaml
 1curly-brace-map: {
 2  "key-1": "value-1",
 3  "key-2": "value-2"
 4}
 5
 6square-bracket-list: [
 7  item-1,
 8  item-2,
 9  item-3
10]
11
12single-line-map: { "key-1": "value-1", "key-2": "value-2" }
13
14single-line-list: [ item-1, item-2, item-3 ]
15
16empty-map: {}
17
18empty-list: []
```

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

### Fractalizer Configuration Syntax

Source: https://terra.polydev.org/config/development/noise/configuring.html

General syntax for defining a fractalizer, where the target sampler is nested under the sampler key.

```yaml
type: <Fractalizer Type>
sampler:
  type: ... # Sampler config to be fractalized
```

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

### MetaString Reference Syntax

Source: https://terra.polydev.org/config/development/meta-configuration.html

Use the ${<reference>} syntax to inject values from external configuration files into strings.

```yaml
thing: ${config.yml:thing1}, ${config.yml:thing2}!
```

```yaml
thing1: Hello
thing2: World
```

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

### Configure Weighted Structure List

Source: https://terra.polydev.org/config/development/pack-from-scratch/grass.html

Demonstrates using a noise sampler to select from a weighted list of blocks.

```yaml
1structures:
2  distribution:
3    type: WHITE_NOISE
4    salt: 4357
5  structures:
6    - BLOCK:minecraft:poppy: 1
7    - BLOCK:minecraft:blue_orchid: 1
8    - BLOCK:minecraft:dandelion: 1
```

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

### Configure Nested Domain Warp Samplers

Source: https://terra.polydev.org/config/development/noise/configuring.html

Demonstrates a multi-level sampler composition where domain warp samplers are nested within each other.

```yaml
type: DOMAIN_WARP
amplitude: 300

sampler:
  type: FBM
  sampler:
    type: OPEN_SIMPLEX_2
    frequency: 0.002

warp:
  type: DOMAIN_WARP
  amplitude: 20

  sampler:
    type: FBM
    sampler:
      type: OPEN_SIMPLEX_2
      frequency: 0.003

  warp:
    type: FBM
    sampler:
      type: OPEN_SIMPLEX_2
      frequency: 0.02
```

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

### Simplify EXPRESSION to EXPRESSION_NORMALIZER

Source: https://terra.polydev.org/config/documentation/objects/NoiseSampler.html

Demonstrates how to replace a standard EXPRESSION sampler with the more concise EXPRESSION_NORMALIZER for simple noise transformations.

```yaml
type: EXPRESSION
expression: (noise(x, z) + 3) / 2
samplers:
  noise:
    dimensions: 2
    type: WHITE_NOISE
```

```yaml
type: EXPRESSION_NORMALIZER
expression: (in + 3) / 2
sampler:
  type: WHITE_NOISE
```

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

### Reusing Data with YAML Anchors

Source: https://terra.polydev.org/config/development/config-data.html

Shows how to define an anchor with '&' and reference it with '*' to avoid duplicating data within a configuration.

```yaml
1some-list-of-data: &the-data-anchor
2  - item-1
3  - item-2
4
5somewhere-where-data-is-reused: *the-data-anchor
```

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

### Define and use functions

Source: https://terra.polydev.org/config/documentation/objects/NoiseSampler.html

Creates reusable logic blocks with arguments that can be called within the expression.

```yaml
type: EXPRESSION

functions:
  addThenDivide:
    arguments:
      - a
      - b
      - c
    expression: (a + b) / c

expression: addThenDivide(3, 2, 10)
```

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

### Create a RegistryKey

Source: https://terra.polydev.org/api/intro/adding-structure.html

Generate a unique RegistryKey using the addon's namespace.

```java
RegistryKey key = addon.key("EXAMPLE_STRUCTURE"); // Create our registry key
```

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

### Define the Addon Manifest

Source: https://terra.polydev.org/api/intro/creating-simple-addon.html

The manifest file must be named terra.addon.yml and placed in the project's resources directory.

```yaml
schema-version: 1
contributors:
  - Terra Contributors
id: example-addon
version: 0.1.0
entrypoints:
  - "com.example.addon.ExampleEntryPoint"
license: MIT License
```

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

### Registering an Event Handler

Source: https://terra.polydev.org/api/intro/listening-for-an-event.html

Configure an event handler for ConfigPackPreLoadEvent using the FunctionalEventHandler API.

```java
platform.getEventManager()
        .getHandler(FunctionalEventHandler.class)
        .register(addon, ConfigPackPreLoadEvent.class)
        .then(event -> {
            logger.info("We're loading a config pack!");
        });
```

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

### Register Biome Addon

Source: https://terra.polydev.org/config/development/pack-from-scratch/introduction.html

Add the config-biome addon to the pack manifest to enable biome creation.

```yaml
1addons:
2  language-yaml: "1.+"
3  chunk-generator-noise-3d: "1.+"
4  config-noise-function: "1.+"
5  palette-block-shortcut: "1.+"
6  config-biome: "1.+"
```

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

### Define custom functions in EXPRESSION

Source: https://terra.polydev.org/config/documentation/objects/NoiseSampler.html

Shows how to define reusable math functions within an EXPRESSION sampler.

```yaml
functions:
  addThenDivide:
    arguments:
        - a
        - b
        - c
    expression: (a + b) / c
```

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

### Combine variables, functions, and samplers

Source: https://terra.polydev.org/config/documentation/objects/NoiseSampler.html

Demonstrates a complex expression integrating multiple features.

```yaml
type: EXPRESSION

variables:
  someConstant: 3
  anotherConstant: 2.5

functions:
  add:
    arguments:
      - a
      - b
    expression: a + b

samplers:
  exampleSampler:
    dimensions: 2
    type: WHITE_NOISE

expression: |
  exampleSampler(x * 2, z * 2) +
  add(someConstant, anotherConstant)
```

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

### Pack Loading Verification

Source: https://terra.polydev.org/config/development/modifying-existing-pack.html

Console output indicating that the custom pack has been successfully loaded by Terra.

```text
[XX:XX:XX INFO]: [Terra] Loading config pack "CUSTOM"
[XX:XX:XX INFO]: [Terra] CUSTOM <PACK VERSION> by <AUTHOR> loaded in XXXX.XXXXms.
```

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

### Configure Addons for NOISE_3D Generator

Source: https://terra.polydev.org/config/development/pack-from-scratch/introduction.html

Add the required core addons to the pack manifest to enable the NOISE_3D generator.

```yaml
addons:
  language-yaml: "1.+"
  chunk-generator-noise-3d: "1.+"
```

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

### Configure Build Files for Terra Projects

Source: https://terra.polydev.org/api/intro/development-environment.html

Build configuration templates for Gradle and Maven projects. Replace API_VERSION and LOADER_VERSION with the desired versions.

```gradle
plugins {
    id 'java'
}

group 'com.dfsek'
version '0.1.0'

repositories {
    mavenCentral()
    maven {
        url "https://repo.codemc.io/repository/maven-public/"
    }
}

dependencies {
    testImplementation 'org.junit.jupiter:junit-jupiter-api:5.8.2'
    testRuntimeOnly 'org.junit.jupiter:junit-jupiter-engine:5.8.2'

    compileOnly 'com.dfsek.terra:api:API_VERSION'
    compileOnly 'com.dfsek.terra:manifest-addon-loader:LOADER_VERSION'
}

test {
    useJUnitPlatform()
}
```

```kotlin
plugins {
    java
}

group = "com.dfsek"
version = "0.1.0"

repositories {
    mavenCentral()
    maven {
        url = uri("https://repo.codemc.io/repository/maven-public/")
    }
}

dependencies {
    testImplementation("org.junit.jupiter:junit-jupiter-api:5.8.2")
    testRuntimeOnly("org.junit.jupiter:junit-jupiter-engine")

    compileOnly("com.dfsek.terra:api:API_VERSION")
    compileOnly("com.dfsek.terra:manifest-addon-loader:LOADER_VERSION")
}

tasks.getByName<Test>("test") {
    useJUnitPlatform()
}
```

```xml
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.dfsek</groupId>
    <artifactId>ExampleAddonMaven</artifactId>
    <version>0.1.0</version>

    <properties>
        <maven.compiler.source>17</maven.compiler.source>
        <maven.compiler.target>17</maven.compiler.target>
    </properties>

    <repositories>
        <repository>
            <id>CodeMC</id>
            <name>CodeMC Maven Repository</name>
            <url>https://repo.codemc.io/repository/maven-public/</url>
        </repository>
    </repositories>

    <dependencies>
        <dependency>
            <groupId>com.dfsek.terra</groupId>
            <artifactId>api</artifactId>
            <version>API_VERSION</version>
            <scope>provided</scope>
        </dependency>
        <dependency>
            <groupId>com.dfsek.terra</groupId>
            <artifactId>manifest-addon-loader</artifactId>
            <version>LOADER_VERSION</version>
            <scope>provided</scope>
        </dependency>
    </dependencies>
</project>
```

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

### Implement ZooTemplate Configuration

Source: https://terra.polydev.org/config/development/config-system.html

Complex configuration using ZooTemplate to nest multiple AnimalTemplate instances.

```YAML
1description: A zoo of Australian animals.
2animals:
3  koala:
4    color: grey
5    legs: 4
6  kangaroo:
7    color: brown
8    legs: 2
```

```JSON
 1{
 2   "description": "A zoo of Australian animals.",
 3   "animals": {
 4      "koala": {
 5         "color": "grey",
 6         "legs": 4
 7      },
 8      "kangaroo": {
 9         "color": "brown",
10         "legs": 2
11      }
12   }
13}
```

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

### Initialize grass feature config

Source: https://terra.polydev.org/config/development/pack-from-scratch/grass.html

Set the initial type and id for the grass_feature.yml file.

```yaml
1id: GRASS_FEATURE
2type: FEATURE
```

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

### Define samplers in EXPRESSION

Source: https://terra.polydev.org/config/documentation/objects/NoiseSampler.html

Shows how to map external samplers for use within an EXPRESSION sampler.

```yaml
samplers:
  whiteNoise:
    dimensions: 2
    type: WHITE_NOISE
```

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

### Define an abstract ore configuration

Source: https://terra.polydev.org/config/development/pack-from-scratch/ores.html

Create a base configuration file to define shared properties like replacement blocks for all ores.

```yaml
1id: ABSTRACT_ORE
2type: ORE
3abstract: true
```

```yaml
1id: ABSTRACT_ORE
2type: ORE
3abstract: true
4
5replace:
6  - minecraft:stone
7  - minecraft:deepslate
```

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

### Implement Keyed in ExampleStructure

Source: https://terra.polydev.org/api/intro/adding-structure.html

Implement the Keyed interface to provide a unique RegistryKey for the structure class.

```java
public class ExampleStructure implements Structure, Keyed<ExampleStructure> {
    private final Platform platform;
    private final RegistryKey key;

    public ExampleStructure(Platform platform, RegistryKey key) {
        this.platform = platform;
        this.key = key;
    }

    @Override
    public boolean generate(Vector3Int location, WritableWorld world, Random random, Rotation rotation) {
        // ... Generation logic
    }

    @Override
    public RegistryKey getRegistryKey() {
        return key;
    }
}
```

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

### Registering a ConfigPackPreLoadEvent Listener

Source: https://terra.polydev.org/api/intro/listening-for-an-event.html

Implements the AddonInitializer interface to register a functional event handler for config pack loading events.

```java
package com.example.addon;

import com.dfsek.terra.addons.manifest.api.AddonInitializer;
import com.dfsek.terra.api.Platform;
import com.dfsek.terra.api.addon.BaseAddon;
import com.dfsek.terra.api.event.events.config.pack.ConfigPackPreLoadEvent;
import com.dfsek.terra.api.event.functional.FunctionalEventHandler;
import com.dfsek.terra.api.inject.annotations.Inject;
import org.slf4j.Logger;

public class ExampleEntryPoint implements AddonInitializer {
    @Inject
    private Logger logger;

    @Inject
    private Platform platform;

    @Inject
    private BaseAddon addon;

    @Override
    public void initialize() {
        logger.info("Hello, World!");

        platform.getEventManager()
                .getHandler(FunctionalEventHandler.class)
                .register(addon, ConfigPackPreLoadEvent.class)
                .then(event -> {
                    logger.info("We're loading a config pack!");
                });
    }
}
```

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

### Configure pack.yml for Schematics

Source: https://terra.polydev.org/config/development/pack-from-scratch/trees.html

Add the structure-sponge-loader addon to your pack manifest to support .schem files.

```yaml
1id: YOUR_PACK_ID
2version: 0.5.0
3
4addons:
5  ...
6  structure-sponge-loader: "1.+"
```

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

### Grass Placement Model Graph

Source: https://terra.polydev.org/config/development/noise/use.html

A Graphviz representation of the noise-based grass placement logic.

```dot
digraph { node [shape=record] input [label="Input|{World Seed|X Coordinate|Y Coordinate}"] sampler [label="White Noise Sampler"] output [label="{Randomized Output|A value from -1 to 1}"] thresholdfunction [label="Threshold Function
If below the threshold (<0), place grass.
(Displayed as a green pixel)"] input -> sampler [label="Passed to"] sampler -> output [label="Produces"] output -> thresholdfunction [label="Passed to"] }
```

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

### SMOOTH Stage Configuration

Source: https://terra.polydev.org/config/documentation/objects/Stage.html

Configures a stage to smooth out noisy borders between pipeline biomes.

```yaml
stages:
  - type: SMOOTH
    sampler:
      type: WHITE_NOISE
```

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

### Obtain Logger via Dependency Injection

Source: https://terra.polydev.org/api/concepts/logging.html

Use this approach within a Manifest Addon Loader entry point to inject a Logger instance.

```java
@Inject
private Logger logger;
```

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

### Define an Integer

Source: https://terra.polydev.org/config/development/config-data.html

Represent whole numbers in configuration files.

```YAML
142
```

```JSON
142
```

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

### Configure Domain Warp Sampler

Source: https://terra.polydev.org/config/development/noise/configuring.html

Basic structure for defining a domain warp sampler configuration.

```yaml
type: DOMAIN_WARP
sampler:
  type: ... # Noise config to be warped
warp:
  type: ... # Warp noise config
```

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

### Correct Pack Manifest Placement

Source: https://terra.polydev.org/config/development/modifying-existing-pack.html

The pack.yml file must be located directly inside the custom pack directory.

```text
Terra/
├── packs/
┆   ├── default.zip
    └── custom-pack/
        ├── pack.yml
        ┆
```

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

### FRACTAL_EXPAND Stage Configuration

Source: https://terra.polydev.org/config/documentation/objects/Stage.html

Configures a stage to reduce fidelity and add fuzzy-ness to pipeline biomes using a noise sampler.

```yaml
stages:
  - type: FRACTAL_EXPAND
    sampler:
      type: WHITE_NOISE
```

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

### Create a Terra world with Multiverse Core

Source: https://terra.polydev.org/install/worldmanager-bukkit-world-creation.html

Use this command to generate a new world using the specified Terra pack ID.

```text
/mv create example_world NORMAL -g Terra:OVERWORLD
```
Tokens:
Raw