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. Using the branch system, other BO3s can be attached to them, forming large structures. BO3s can also have NBT data attached to them to fill chests, furnaces, dispensers and other Tile Entities. However, the main .bo3 files are plaintext. Notepad is able to open them.

##Getting BO3s There are a few tools available 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.

##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. 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. This setting manages the number of attempts to spawn the object for each chunk hen using the CustomObject resource (Tree and CustomStructure have their own parameters, Sapling always tries to spawn exactly one tree). If you have very strict spawn conditions you might want to increase this.

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. So one time the BO3 faces north, another time the BO3 faces east. This should usually be set to true.

SpawnHeight:highestBlock

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

MinHeight:0

MaxHeight:256

The minimum and maximum height for the BO3 to spawn. Inclusive.

MaxBranchDepth:9

When spawned as a structure, 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. When you aren't using branches, you won't need this.

ExcludedBiomes:All

When spawned with the UseWorld or UseWorldAll keywords, this BO3 should NOT spawn in the following biomes.

If you don't use UseWorld or UseWorldAll to spawn this object, for example because you use CustomObject(thisObjectName) in the BiomeConfigs, this will have no effect.

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. Used in combination with the next setting.

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, so that the terrain will overwrite the BO3.

placeAnyway - place the block anyway, so that the BO3 will override the terrain.

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. Blocks can have NBT files attached to them to provide extra data, like the contents of the chest or the instructions for a mob spawner. See here for information on how to create the NBT files.

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.

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 like C:/Users/Bob/Minecraft/file.nbt are not accepted, but it is possible to use ../ to move up one or more folders. Windows is case-insensitive (Chest.nbt and chest.nbt are the same) and also allows you to use both slashes (\ and /), other operating systems are case-sensitive and only allow only the forward slash (/).

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 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 will execute it's spawn checks (BlockCheck, LightCheck, etc.). However, if the object fails to spawn, it won't cancel the whole structure: just one part will be missing. This had to be done because of technical restrictions (see here).

As of 2.5.0 there are two types of Branching, Branch(...) and WeightedBranch(...)

#####Branch(...) Syntax (Pre-2.5.0):

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

Syntax (As of 2.5.0):

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

ObjectName: The name of another object to be spawned as a branch. It doesn't have to be a BO3 object, it can also be a BO2 object.

ObjectRotation: 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.

ObjectChance: The number out of 100 that you wish an object to spawn out of (As of 2.5.0, you may use decimal numbers, i.e. 33.33). This is an object independent chance; that is, ObjectName is given a chance to spawn and if it fails, a new random is generated for each subsequent object and is given a chance to spawn. This will continue until a successful spawn or all objects have been given a chance to spawn.

Example: Branch(x,y,z,Branch1,NORTH,50,Branch2,NORTH,75)

This will give Branch1 a 50/100 chance to spawn, if this fails Branch2 will be given a 75/100 chance to spawn, and if that fails nothing will spawn.

IndividualChance: Looking at ObjectChance, notice that it is out of 100. With IndividualChance, you can change this 100 to be whatever you want. This value can be either an integer or decimal.

Example: Branch(x,y,z,Branch1,NORTH,1.5,Branch2,NORTH,3.25,5)

This will give Branch1 a 1.5 in 5 chance to spawn, if this fails Branch2 will be given a 3.25 in 5 chance to spawn, and if that fails nothing will spawn.

#####WeightedBranch(...) Syntax (As of 2.5.0):

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

ObjectChance: The number out of the sum of all ObjectChance''s that you wish an object to spawn out of. This is an object dependent chance; that is, ObjectName is given a chance to spawn and if it fails, each subsequent object is given a chance to spawn from the same random number out of the sum of chances. This will continue until a successful spawn or all objects have been given a chance to spawn.

Example: WeightedBranch(x,y,z,Branch1,NORTH,50,Branch2,NORTH,75)

This results in Branch1 having a 50/125 chance to spawn (125 is from 50+75) and Branch2 will have a 75/125 chance to spawn. A spawn is guaranteed to happen.

TotalChance: Looking at ObjectChance, notice that it is out of the sum of ObjectChances. This prevents you from having a chance for nothing to spawn. With TotalChance, you can change this to be whatever you want. This value can be either an integer or decimal.

Example: Branch(x,y,z,Branch1,NORTH,1.5,Branch2,NORTH,3.25,5)

This result in Branch1 having a 1.5 in 5 chance to spawn, Branch2 will have a 3.25 in 5 chance to spawn, and there is a 0.25 in 5 chance that nothing will spawn.

###NBT Although BO3 files are plaintext files, attached Tile Entities need to be placed in NBT attachment 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.

The NBT attachement file should contain a properly structured Tile Entity. Location data is ignored, so don't worry if your NBT editor adds it. The data can be placed directly in the root of the file, or wrapped in a compound tag.

Screenshot of a properly formatted chest. Here the data is wrapped in a compound tag called Data. It is also allowed to place the data directly in the root of the file.