BO3 objects

BO3 objects (also called custom biome objects (BOBs) version 3) are the successor of the BO2 objects. They 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 from a WorldEdit selection.
• (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 one world 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 BO3 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(...), CustomStructure(...), CustomObject(...)

• Trees should, just like the vanilla trees, use Tree. BO3 objects that have their Tree settings set to false won't be able to use this structure.
• Structures (BO3s which spawn other BO3s, forming structures) should use CustomStructure.
• Everything else should use CustomObject. If you are not sure which resource you should use, you'll most likely need this one.

Growing BO3s from saplings

One cool feature is that custom trees can be grown from saplings. You'll need to use the Sapling "resource" for this. Sapling is not a real resource, as it isn't used by the world generator. To make this more clear, it has its own section in the BiomeConfigs, instead of being in the resources queue. Just like Tree, it only accepts vanilla trees or objects which have Tree set to true. See here for more information about its syntax.

Keywords

There are several keywords available which can be used as a special 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 - atMinY, 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 and entities

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,blockId[,NBT data])
• RandomBlock(x,y,z,blockId[,NBT data],chance[,blockId[,NBT data],chance[,...]])

blockId is the id of the block, for example minecraft:stone. NBT data can be the file name of an NBT file, or inline NBT, or a custom name for the block.

So Block(0,0,0,minecraft:stone) spawns a stone block at the BO3 origin.

Complex example: RandomBlock(0,0,0,minecraft:chest,chest.nbt,50,minecraft: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.

Besides blocks, you can also place entities.

Entity(x,y,z,entityId,groupSize[,NBT data])

entityId is something like minecraft:cow. See the Minecraft Wiki for a list of all entity ids).

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,blockId[,otherBlockId[,...]])

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

BlockCheck(0,-1,0,minecraft:grass,minecrat:dirt) - require grass or dirt one block below the origin of the BO3.

BlockCheck(0,-1,0,minecraft:grass)
BlockCheck(0,-2,0,minecraft: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 10x10 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).

There are two types of branching, Branch(...) and WeightedBranch(...)

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(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

Block(..), RandomBlock(..) and Entity(..) all take NBT data. There are multiple ways to define this data.

If you provide some arbitrary text as NBT, like Bobbie, then that will become the custom name of the block/entity. Technically, Bobbie is translated to the structure {CustomName:Bobbie,CustomNameVisible:1b}.

If you provide some text starting with a {, then it will be parsed in the same way as NBT in Minecraft commands, so like in /give, /summon, etc.

And finally, if you provide a filename, like extradata.nbt, the file will be opened and the NBT inside will be read. You can navigate to another folder: mydata/extradata.nbt looks inside the mydata folder in the GlobalObjects or WorldObjects folder (even if the BO3 itself is placed in a subfolder of GlobalObjects or WorldObjects). You cannot use absolute paths; C:\Users\Bob\somedata.nbt is forbidden. However, you can use the ../-notation to go up folders.

You can either use binary NBT files (file name needs to end with .nbt or .dat) or textual NBT files (.txt). The binary files follow the same format as for example the player data files in your world. Those files can only be opened by specialized programs such as NBTExplorer. The textual files follow the same format as the Minecraft commands, and can be edited by any text editor.

The NBT attachment file should contain a properly structured Tile Entity. The "id", "x", "y" and "z" tags are ignored; TerrainControl overwrites them.

The advantage of using a binary file over a text file is that once you have an NBT editor installed, you can get a nice overview of the contents of your file. Text files can get quite messy if they become big. An advantage of text files is that they do not require specialized software to open and edit them; any text editor will do.

Screenshot of a properly formatted chest. Here the data is wrapped in a compound tag called Data. This is allowed for binary files, since Minecraft previously didn't allow multiple tags in the root of the file. Nowadays, this hack is no longer needed, and you can directly place the tags in the root of the file. For backwards compatibility, binary files structured like this can still be read.