Bukkit

Design Spec for Biome Object Builder v2 File Format

File Extension .BO2


File Structure
[META]
<tags>
[DATA]
<blocks>



[META]
<tags> can be 0 or more of the following:
<option>=<type>
tags are optional, if they are not present, their default value is used instead.


<type> can be one of the following:
<string> - Any number of characters terminated by a new line
<int> - Any signed integer
<bool> - Either "True" or "False"
or a list of types deliminated by ,
For example <string>,<string>,<string>


Possible <option>s:
version=<string>          [Default: NA]    
spawnOnBlockType=<intList>[Default: 2]     [Bound: Must be a natural block ID]
spawnSunlight=<bool>      [Default: True]
spawnDarkness=<bool>      [Default: False]
spawnWater=<bool>         [Default: False]
spawnLava=<bool>          [Default: False]
underFill=<bool>          [Default: True]
dig=<bool>                [Default: True]
needsFoundation=<boo>     [Default: True]
rarity=<int>              [Default: 10]    [Bound: Min = 1, Max = 1000]
collisionPercentage=<int> [Default: 2]     [Bound: Min = 1, Max = 100]
spawnElevationMin=<int>   [Default: 0]     [Bound: Min = 0, Max = 128, Min <= Max]
spawnElevationMax=<int>   [Default: 128]   [Bound: Min = 0, Max = 128, Max >= Min]
randomRotation=<bool>     [Default: True]
groupId=<string>          [Default: ""]
tree=<bool>               [Default: false]
branch=<bool>             [Default: false]
diggingBranch=<bool>      [Default: false]
branchLimit=<int>         [Default: 6]     [Bound: Min = 1, Max = 16]
groupFrequencyMin=<int>   [Default: 1]     [Bound: Min = 1, Max = 100, Min <= Max]
groupFrequencyMax=<int>   [Default: 5]     [Bound: Min = 1, Max = 100, Max >= Min]
groupSeperationMin=<int>  [Default: 0]     [Bound: Min = 0, Max = 16, Min <= Max]
groupSeperationMax=<int>  [Default: 5]     [Bound: Min = 0, Max = 16, Max >= Min]
spawnInBiome=<stringList> [Default: "All"] [Bound: Only valid Biomes and "All"]


Descriptions of options:
version            - contains a string of the current version of the file structure.

spawnOnBlockType   - contains a list of integer values of the block ids this object can spawn on.

spawnSunlight      - a flag if this object can spawn on sunlit ground

spawnDarkness      - a flag if this object can spawn in total darkness

spawnWater         - a flag if this object can spawn under water. (Note if the object is tall enough, it might portrude from the water)

spawnLava          - a flag if this object can spawn under lava.

underFill          - a flag to determin if the object should have its base filled underneath of any gaps after placing. The gaps will be filled with the block specified in spawnOnBlockType.

needsFoundation    - a flag to determin if the object requires a preexisting foundation. If this is false, the object MIGHT spawn floating.

dig                - a flag to determin if the object should dig out the sides of its area. This will reduce the frequency bailout chance drasticly.

rarity             - a 1 to 100 chance the object will spawn in any given chunk. However, each whole 100 value represents a spawn attempt, then the remainin is a precentage again (ex: rarity=320 means that there will be 3 spawn attempts plus a 20% chance of a 4th)

collisionPercentage- a 1 to 100 percent of the total object that is allowed to collide with the terrain. With the dig flag set to flase, collsion blocks are removed, with the dig flag of true, collsion blocks from the object will override terrain.

spawnElevationMin  - an integer indicating the minimum elevation the base of the object can spawn at.

spawnElevationMax  - an integer indicating the maximum elevation the base of the object can spawn at.

randomRotation     - a flag to determin if the object can be rotated randomly 0, 90, 180 or 270 degrees on placing. A branch block will be oriented based on the branch direction, however with this flag set, it can appear in any direction.

groupId            - a string containing the group id this object belongs to. Objects with the same groupId can spawn near each other. (If group ID is absent, or "", no other group information needs to be loaded, or saved to file)

tree               - a flag to determin if this object should grow from saplings

branch             - a flag to determin if this object should spawn from branch blocks

diggingBranch      - a flag to determin if the branch block is allowed to override existing blocks in the object. If false if the branch would overlap the existing object, it fails to be added, and the branch fails completely.

branchLimit        - The maximum number of branches a single object can have before the branch engine stops adding branches

groupFrequencyMin  - The minimum number of objects from a group that are attempted to be placed near each other.

groupFrequencyMax  - The maximum number of objects from a group that are attempted to be placed near each other. (groupFrequency is calculated for each normal frequency attempt!, so be careful about setting your numbers too high)

groupSeperationMin - The minimum distance between group objects when spawning.

groupSeperationMax - The maximum distance between group objects when spawning.

spawnInBiome       - a list of strings of possible biomes the object can spawn in. The possibilities are "All" or the name of the Biome, such as "Tundra" or "Desert"


[DATA]
<blocks> can be 0 or more of:
<location>:<block>[.<option>[#<branch>]]


A <location> is:
<int>,<int>,<int>
It is in the form of Y,X,Z where Z is elevation.
The center block of the object is at 0,0,0.
The center block is used for calculations about spawning
Z may be negative, if so, the object will displace blocks beneath its base, as it "digs" down.


A <block> is:
<int>
It is the block ID of the given block. Air blocks do not need to be specified, but if they are not, then it is possible that enclosures might be partially filled if the dig flag is not set.


A <otpion> is:
<int>
This is the extra data stored in the block id. It is used for setting meta block data. Forexample, Crop age is based on option values 0 - 7


A <branch> is:
<int>@<int>
The first <int> in a value 0-3 representing 0=North, 1=East, 2=South, 3=West
The second <int> is a value 1-100 representing the percent chance this branch block could become a branch in a given group.

Notes on placement:

• If an object would extend past the top of the sky, it will fail to be placed.
• If an object would try to replace a bedrock block, it will fail to be placed.
• if max(Z) - min(Z) >= 128, the object will not be able to be placed. Even objects that have large heights (deltaZ > 32) are unlikely to be placed.

Notes on branch spawning:

• Branch blocks that are adjacent to each other, are considered 1 branch region. The block closest to the origin takes precidence for deciding direction and probability. Other branch block info is ignored. (Diagonally adjacent blocks do not count) When replacing these adjacent branch blocks, you should replace all of them at the same time with (if any) from the branch object.
• When a branch object is spawned from a branch block, it is rotated so that it's north is the direction specified in the branch block. (Then if random rotation is in effect, then it is rotated further)