BO3 objects

BO3 objects (also called custom biome objects (BOBs) version 3) are the successor of the BO2 objects. It are objects consisting of blocks that can spawn in your biomes. They can represent trees, ores, dungeons and many more things. Unlike BO2s, they support NBT data (for items in chests and mobs in spawners) and random blocks. Using the branch system, other objects, including BO2s, can be attached to them, forming large structures.

##Getting BO3s Although BO3s are quite new, there are already multiple tools to create BO3s.

BO3-Tweaks by Elzaar and LanToaster. Command-line application to tweak BO3s.
BO3Tools by Rutger Kok. Bukkit plugin to create BO3s.
(Terrain Control itself will clean up the BO3 file if the SettingsMode isn't WriteDisable. It will add missing settings, reset the comments and remove everything it doesn't understand.)

Two simple example BO3s can be found here.

###NBT editors For the additional data in the BO3s you need to make NBT files. Here are some editors:

NBTExplorer - stand-alone NBT editor.
PowerNBT - CraftBukkit plugin that provides a command based in-game NBT editor. Can export the Tile Entity you are looking at as a NBT file that is compatible with Terrain Control.
In-Game NBTEdit - Forge mod that provides an in-game user interface for editing NBT files.

##Placing the BO3s in your world Placing the BO3 in your world consists of two steps. First you place the object file in one of the BOB folders and then you add it to one of the BiomeConfigs.

There are two different BOB folders. One folder is the global folder; all your Terrain Control worlds can use the BO3. On Bukkit it's path is plugins/TerrainControl/GlobalObjects and on Forge it is mods/TerrainControl/GlobalObjects. The other folder is the local folder; only the world in which you have placed the BO3 in can use it. The path is plugins/TerrainControl/worlds/*worldname*/WorldObjects for Bukkit and mods/TerrainControl/worlds/*worldname*/WorldObjects for Forge. If you plan to use the BO2 in multiple worlds, you can better place it in the global folder.

After all the objects are placed in one of the folders you can add them to your world. There are several ways to spawn a BO2:

In the BiomeConfigs, there are multiple ways to spawn a BO3. You can use the following resources:

Tree(...), CustomObject(...), CustomStructure(...) and Sapling(...)

Tree is used for both the vanilla trees and the custom trees spawning during chunk generation. BO3 objects that have Tree set to false won't be able to use this structure.
CustomObject can be used for all custom objects. It tries to spawn each object in it's list.
CustomStructure is slower than CustomObject and it can only be once in each BiomeConfig, but it will generate the branches of each object. It only accepts objects which actually have branches attached.
Sapling isn't used during world generation, but instead when a sapling grows. Just like Tree, it only accepts vanilla trees or objects which have Tree set to true.

###Keywords There are several keywords available which can be used as an object name in all the resources except CustomStructure:

UseWorld, UseWorldAll, UseBiome and UseBiomeAll

UseWorld tries to spawn one of the objects in the WorldObjects folder. If the object cannot spawn in the biome (see the ExcludedBiomes setting of the BO3) it will fail to spawn.
UseWorldAll tries to spawn a all of the objects in the WorldObjects folder. If an object cannot spawn in the biome (see the ExcludedBiomes setting of the BO3) that object will fail to spawn.
UseBiome tries to spawn one of the objects of the BiomeObjects setting in the BiomeConfig.
UseBiomeAll tries to spawn all of the objects of the BiomeObjects setting in the BiomeConfig.

The settings in the BO3 file

BO3 object

Author:Unknown

The author of the BO3 object. Not used by Terrain Control, but it can be used by an external application.

Description:No description given

A short description of the BO3 object. Not used by Terrain Control, but it can be used by an external application.

Version:3

BO3s have version number three. Don't change this! It can be used by external applications to do a version check.

SettingsMode:WriteAll

Normally, each time Terrain Control reads the BO3 object, it also writes to it. With this setting you can change how Terrain Control writes to this BO3. Possible modes:

WriteAll - Autoupdate settings from old versions, order them, add comments, reset invalid settings and remove custom comments.

WriteWithoutComments - Same as WriteAll, but removes all comments, both the ones of Terrain Control and your own.

WriteDisable - Don't write to the comment files. Errors are not corrected, old settings are read, but they are also not corrected. Custom comments won't be removed with this mode.

Main settings

Tree:true

This needs to be set to true to spawn the object in the Tree and Sapling resources.

Frequency:1

The frequency of the BO3 from 1 to 200. Tries this many times to spawn this BO3 in a chunk when using the CustomObject(...) resource.

Rarity:100.0

The rarity of the BO3 from 0 to 100. Each spawn attempt has rarity% chance to succeed when using the CustomObject(...) resource.

The rarity can be very small. 0.0001 is possible.

RotateRandomly:false

If you set this to true, the BO3 will be placed with a random rotation.

SpawnHeight:highestBlock

The spawn height of the BO3 - randomY, highestBlock or highestSolidBlock.

MinHeight:0

MaxHeight:256

The minimum and maximum height for the BO3 to spawn.

MaxBranchDepth:9

Objects can have other objects attacthed to it: branches. Branches can also have branches attached to it, which can also have branches, etc. This maximum branch depth for this object.

ExcludedBiomes:

When spawned with the UseWorld keyword, this BO3 should NOT spawn in the following biomes.

If you write the BO3 name directly in the BiomeConfigs, this will be ignored.

ExcludedBiomes:All will make this object not spawn in UseWorld.

Source block settings

SourceBlock:0

The id of the block the BO3 should spawn in.

OutsideSourceBlock:placeAnyway

What to do when the BO3 should do when it is about to place a block on a location where there is no source block.

dontPlace - cancel the block placement on that location.

placeAnyway - place the block anyway.

MaxPercentageOutsideSourceBlock:100

A percentage of how much block of the BO3 can be outside the source block.

Some examples:

A tree should spawn inside air blocks, so we set SourceBlock to 0, the id of air. Leaves shouldn't replace stone, so we set OutsideSourceBlock to dontPlace. We don't want the tree to be covered too much with terrain, so we set MaxPercentageOutsideSourceBlock to 10, so that at least 90% of our tree will spawn.

An ore should spawn in stone, so we set SourceBlock to 1, the id of stone. The ore shouldn't stick out of the stone, so we set OutsideSourceBlock to dontPlace. We don't mind only a small part of our ore spawning, so we set MaxPercentageOutsideSourceBlock to 90.

Blocks

All the blocks used in the BO3 are listed here.

There are two block functions:

Block(x,y,z,id[:data][,nbtfile.nbt])

RandomBlock(x,y,z,id[:data][,nbtfile.nbt],chance[,id[:data][,nbtfile.nbt],chance[,...]])

Example: RandomBlock(0,0,0,CHEST,chest.nbt,50,CHEST,anotherchest.nbt,100) will spawn a chest at the BO3 origin, and give it a 50% chance to have the contents of chest.nbt, or, if that fails, a 100% percent chance to have the contents of anotherchest.nbt.

The NBT file needs to contain a compound tag, which should contain a properly structured Tile Entity. Location data is ignored, so don't worry if your NBT editor adds it.

Screenshot of a properly formatted chest

You can use relative paths in your BO3. So chests/chest.nbt will search for chest.nbt inside the chests folder, which should be placed next to the BO3. Absolute paths are not accepted. Windows is case-insensitive and also allows you to use the blackslash(\), other operating systems don't.

BO3 checks

You can add as many checks to the BO3 as you want. If any of these checks fails, the BO3 will fail to spawn. Everything is checked before the BO3 spawns.

BlockCheck(x,y,z,id[.data][,id[.data][,...]])

Require a block to be on this location before the BO3 spawns there. Examples:

BlockCheck(0,-1,0,GRASS,DIRT) - require grass or dirt one block below the origin of the BO3.

BlockCheck(0,-1,0,GRASS)
BlockCheck(0,-2,0,DIRT)
Require grass one block below the origin of the BO3, and dirt one block below that.

LightCheck(x,y,z,minLight,maxLight)

Require a certain light level on a certain position. Light values are inclusive, so LightCheck(0,0,0,5,7) requires a light level of 5, 6 or 7 at the BO3 origin.

###Branches When using the CustomStructure resource these objects (called branches) will be attached to the current object. Those branches are also able to have branches. While individual objects cannot be larger than a chunk (16x256x16) structures can be much larger, up to 11x11 chunks.

The syntax is:

Branch(x,y,z,ObjectName,ObjectRotation,ObjectChance[,AnotherObjectName,ObjectRotation,ObjectChance[,...]])

ObjectName is the name of another object. It doesn't have to be a BO3 object, it can also be a BO2 object.

ObjectRotation is the rotation in which the object will spawn - NORTH, SOUTH, EAST or WEST. This is relative to the object it is attached to. The RotateRandomly setting of the branch is ignored.

The y-coordinate won't do anything if the SpawnHeight of the object that started the structure is set to highestBlock or highestSolidBlock. Instead, all branches will spawn on the highest (solid) block.

Any object that can have branches won't execute it's spawn checks (BlockCheck, LightCheck, etc.). This had to be done because of technical restrictions (see here).