BDCFF extension for the "Cross Development C64 engine" and "Crazy Dream PC"

3-dec-2008 wip (subject to change during developement)

The structure

[highscores]
666666 LogicDeLuxe
666665 Prof Knibble
666664 No One
; Can contain several lines of
; Scores Name
; The first rank is listed first, followed by the second etc.
; Available only in [game] section
[/highscores]

[mapcodes]
; extended codes for map-coded caves, may be absent.
Length=1        ; The length (1 or 2 characters) of the map-codes. Default value = 1
; For example,
.=DIRT
W=STEELWALL
; ...etc. If Length = 2 then ..=DIRT, Ws=STEELWALL, etc.
[/mapcodes]

[cave]
; cave data and attributes
Size=6 5

[demo]
; demo data for this cave, all demo may be in one line, i.e. .30uLtf4curCDRr7 etc.
.30     ; no movement for 30 turns
u       ; move up one space
L       ; snap left without moving. ie the fire button was pressed during this move.
t       ; A true random number decision was true. For instance, this could be required for an amoeba.
f4      ; The next 4 true random number decisions were false.
cur     ; combined move up and right. cru is synonymous for that and can be used as well. (Diagonal movement enabled.)
CDR     ; combined snap down right. CRD is synonymous.
r7      ; move right 7 spaces
; etc.
[/demo]

[objects]
; cave objects data, this is absent if cave is map-coded.
; For example,
Point=1 1 INBOX
Line=2 1 2 4 DIAMOND
Point=4 3 OUTBOX
[Level=4,5]
; Here goes a firefly in levels 4 and 5 only.
Point=4 4 FIREFLYl
[/Level]
[/objects]

[/cave]

[cave]
; next cave, etc.

[map]
; a map of a cave, is absent if cave is object-coded.
; For example,
WWWWWW
WXd..W
W.d..W
W.d..W
W.d.PW
WWWWWW
[/map]

[/cave]

[/game]

[/BDCFF]

The Attributes

AcidProperties

Element to eat, growth propability (BDCFF defaults = DIRT 0.03)

AltDirt

[never]|[element1 [element2]]
Use alternative Dirt graphics when one of those elements are in the cave.
Some example games use these values:
Original Boulder Dash 2: AltDirt=AMOEBA
No One Packer 5.x: AltDirt=AMOEBA SLIME
BD1, PLCK, Profi-Boulder series: AltDirt=never

The engine shouldn't use it regardless, but use it wisely, since it depends on the used graphics set, whether it makes any sense or not.
Alternative Dirt graphics can be forced on with DIRTLOOKSLIKEeffect=DIRT2

AmoebaGrowthProb

Amoeba slow (and fast) growth probability (two or one number, BDCFF-native defaults = 0.03125 0.25)

AmoebaProperties

AmoebaProperties.waitforhatching=true|false
AmoebaProperties.immediately=true|false
If waitforhatching=true, the timer does not start befor the guy's hatching, even in case the Amoeba is free to grow before this happens.
If immediately=true, the timer does start immediately, no matter if the Amoeba is activated or still inactive. If immediately=false, the Amoeba timer does not start before the Amoeba comes to life.

defaults:
waitforhatching=true for 1stB, CrLi, false for BDCFF-native, BD1, BD2, PLCK
immediately=true for BD1, false for all other engines and BDCFF-native

AmoebaThreshold

The percentage of the cave the amoeba is allowed to occupy before turning to boulders. (number, BDCFF-native = 0.2273).

AmoebaTime

Amoeba slow growth time (number, BDCFF-native = 999)

Amoeba2GrowthProb

Amoeba2 slow (and fast) growth probability (two or one number, default values = 0.03125 and 0.25)

Amoeba2Properties

Amoeba2Properties.waitforhatching=true|false
Amoeba2Properties.immediately=true|false
Amoeba2Properties.explode=true|false
If waitforhatching=true, the timer does not start befor the guy's hatching, even in case the Amoeba2 is free to grow before this happens.
If immediately=true, the timer does start immediately, no matter if the Amoeba2 is activated or still inactive. If immediately=false, the Amoeba2 timer does not start before the Amoeba2 comes to life.
If explode=true, an amoeba2 piece will explode when it touches an amoeba piece.

defaults:
waitforhatching=true for 1stB, CrLi, false for BDCFF-native, BD1, BD2, PLCK
immediately=true for BD1, false for all other engines and BDCFF-native
explode=true for BDCFF-native

Amoeba2Threshold

The percentage of the cave the amoeba2 is allowed to occupy before turning to boulders. (number, BDCFF-native = 0.2272).

Amoeba2Time

Amoeba2 slow growth time (number, BDCFF-native = 999)

Author

Cave (or game) author (string, for cave default equals game author)

BiterProperties

Delay; Element to eat (default=0 DIAMOND)

BladderProperties

Colides with (BDCFF-native = DUMMY)

BonusLife

Bonus life score (number, BDCFF-native = 500)

BonusTime

Reward for collecting a clock (one or one number for each level, BDCFF-native = 30)

BorderProperties

BorderProperties.scan=true|false
BorderProperties.effect=true|false
BorderProperties.wraparound=true|false
BorderProperties.lineshift=true|false
BorderProperties.perfectwrap=true|false
If scan=true, Inbox and Outbox will work on upper and lower borders, things can move from those borders and Amoebas are counted.
If effect=true, the effect table is processed in the upper and lower border. If set to false, element which move to those borders are stuck there forever and Explosion sequences aren't executed either.
If wraparound=true, elements leaving the upper or lower border appear on the opposite border.
If lineshift=true, elements leaving the right border reappear one line lower at the left, and elements leaving the left border reappear one line higher on the right. This also affects the drawing of cave objects, so set this property first. XDC is always lineshifting.
If perfectwrap=true, upper and lower wraparound is calculated with redirection. If set to false, only movements are redirected, but interaction is implemented with copying the borders above/bellow the cave between scan intervals, which is faster, but has side effects which needs to be emulated.
Note that wrapping left/right is always possible as C64 engine merely see a continues array in RAM.

defaults:
scan=true for BD1, 1stB, CrLi, false for PLCK
effect=true for 1stB, CrLi, false for BD1, BD2, PLCK
wraparound=true for 1stB, CrLi, false for BD1, BD2, PLCK
lineshift=true for all C64 engines, false for BDCFF-native
perfectwrap=true for BDCFF-native, false for all C64 engines

CaveScheduling

For emulating a certain timing model. Can be ms, bd1, bd1atari, bd2, bd2ckatari, plck, crdr7. This requires CaveDelay to be specified to work, except for ms. If the engine isn't able to keep up with the intended speed for performance reasons, all timers must slow down with it to keep things in sync. (BDCFF-native default = ms)

CaveDelay

Used in BoulderDash Construction Kit engine. One number for each level. If CaveDelay and FrameTime are specified in the same cave, the engine shall use the one it best supports. This value is ignored when CaveScheduling is set to ms. This value is translated to ms by BDCFFcompiler and will be used if no FrameTime is given.

CaveMaxTime

If you reach that number by collecting too many clocks, the time overflows to 0. (BDCFF-native default = 999)

CaveSize

Global cave dimensions. Can be overridden with the Size attribute. Available only in [game] section.

defaults: 40 22

CaveTime

Cave total times for each level (one or one number for each level). Available only in [cave] section (BDCFF default = 999)

Charset

Character set, for example "space" for BD3, default = "original"

Colors

Colors=[border background] foreground1 foreground2 foreground3 [amoeba slime]
Cave colors (string, 3 or 5 or 7 C64 color names, Atari color names, C64DTV color names or hexadecimal RGB triples 000000 - ffffff.) If five names are given, border and background is always listed first. Specifying amoeba and slime color is only possible when 7 names are given. Slime color is not supported by XDC, but should be specified along with amoeba anyways.
Valid names are Black, White, Red, Cyan, Purple, Green, Blue, Yellow, Orange, Brown, LightRed, Gray1, Gray2, LightGreen, LightBlue and Gray3. On C64 engines, foreground 3 is limited to the first 8 colors. In XDC, this limitation can be exchanged for a limited background color.
Atari colors consist of the string "AtariCL" where C is the hue (chroma value) and L is the brighness (luma value). C=0 specifies a shade of gray. C and L are hex nybles and can have any value from 0 to F. C64DTV colors are named "C64dtvCL" and work exactly like Atari colors, except that the hue is a bit different.

BDCFF-nativedefaults: the engine should choose some useful colors randomly if nothing is specified.

Date

Date of cave (or game) creating (string, 2002 or 2002-10 or 2002-10-31 format)

Description

Cave (or game) description (string)

DiagonalMovement

The guy can move diagonal. (BDCFF-native default = false)

DiamondsRequired

Number of diamonds required to successfully finish the cave for each level (one or one number for each level). Zero or negative values are subtracted from the currently available amount of diamonds at the time of hatching. (BDCFF-native default = 10)

DiamondValue

Number of points per collected diamond (two or one numbers, second value is number of bonus points per diamond)
While the engine is required to work with only one number here, it is highly recommended to use always two numbers for this, due to an interpretation conflict. (BDCFF native defaults: 0 0)

Difficulty

Difficulty of the game (or level). For info purposes

DummyProperties

DummyProperties.diamondcollector=true|false
DummyProperties.penalty=true|false
DummyProperties.destructable=true|false
If diamondcollector=true, the Diamonds are collected and counted when dropped on a Dummy, otherwise they just remain lying there.
If penalty=true, the Dummy converts to a TIMEPENALTY surrounded by STEELWALLBIRTH1 when a Boulder is dropped on it, otherwise it just remain lying there.
If destructable=true, Dummies can be destroyed when being in range of an explosion, otherwise they convert to a Time Penalty when caught by an explosion, and they are completely immune to Bomb explosions.

defaults:
diamondcollector=true for 1stB, CrLi, false for BD1, BD2, PLCK, XDC, BDCFF-native
penalty=true for 1stB, CrLi, false for BD1, BD2, PLCK, XDC, BDCFF-native
destructable=true for BD1, BD2, PLCK, XDC, BDCFF-native, false for 1stB, CrLi

Effect

element1 element2
This applies a Lord Diego-Effect, except it is much more general. There may be several Effect attributes.
Replaces element 1 with element 2 in the effect table.

EnemyDirectionProperties

EnemyDirectionProperties.time time
EnemyDirectionProperties.startbackwards true|false
EnemyDirectionProperties.changeathatching true|false
time is given in seconds. If time=0, no auto direction changes occur.
startbackwards does just that.
changeathatching is only affective if time>0.
The timer does not start before the hatching.
     defaults:

time=0 for any engine and BDCFF-native
startbackwards=false for any engine and BDCFF-native
changeathatching=true for 1stB, false for any other engine and BDCFF-native

Fingerprint

Is used to validate a demo recording or a highscore table which makes it authentic for competition purposes.
For validating a demo recording, the Fingerprint is placed at the end in the [demo]-section. This is a CRC of the Executable, the demofile (if it is not part of the BDCFF-file) and the [game]-section including all its [cave]-sections. Nested existing other [demo]-sections, [highscore]-sections and the Fingerprint itself are excluded from the CRC.
For validating a highscore table, the Fingerprint is placed in the end of the [highscore]-section. This is a CRC of the Executable and the BDCFF-file, but all [demo]-sections are excluded from the CRC.

Fontset

Font set, for example "space" for BD3, default = "original"

FrameTime

Given in milliseconds, one or one number for each level. (200 means 200 ms = 5 steps per second.) If CaveDelay and FrameTime are specified in the same cave, the engine shall use the one it best supports. XDC supports 1 - 255 ms, but values <100 shouldn't be used for performance reasons. (BDCFF-native default = 200)

HatchingDelay

The guy's hatching delay. This is the number of scanning frames inbox will be flashing before the guy's hatching. (one or one number for each level, BDCFF-native default = 21). If not given, XDC's BDCFF converter will calculate a HatchingDelay to match 2 seconds.

HatchingTime

Like HatchingDelay, but given in seconds. (BDCFF-native default = 2 seconds in C64 Scheduling) XDC's BDCFF converter will calculate a HatchingDelay to match this value, as long as it doesn't exceed 255.

InitialBorder

Initial border element. This element is used to draw the border. Special attention should go to BDCFF version <= 0.32: In files having such a version or no version given, and if the cave is object based, the engine should check if objects are drawn beyond the visible 20x12 part. If nothing is drawn in the invisible part, the InitialBorder should be drawn around the visible part and the invisible part should be filled with it as well. BDCFF-native default is STEELWALL.

InitialFill

Initial fill element. This element is used to fill entire field, except for the border. BDCFF-native default is DIRT.

InOutBoxProperties

InOutBoxProperties.forceflashing=true|false
InOutBoxProperties.hatchpattern=true|false
InOutBoxProperties.synchronous=true|false
If forceflashing=true, flashing is forced by alternating the state of the first box in cave on each scan. If set to false, boxes won't flash in case there is an even number of them.
If hatchpattern=true, the guy's hatching can only occur from the empty state of a box, which result in a pattern of appearance.
If synchronous=true, all boxes are drawn in the same state (full/empty) on one scan.

forceflashing=true for 1stB, CrLi, XDC, false for BD1, BD2, PLCK
hatchpattern=true for all C64 engines
synchronous=false for all C64 engines

Intermission

Is intermission (boolean, BDCFF-native default = false). Available only in [cave] section.

IntermissionProperties

IntermissionProperties.instantlife=true|false
IntermissionProperties.rewardlife=true|false
If instantlife=true, an extra life is given whenever an intermission is reached, unless the maximum number of lives are reached.
If rewardlife=true, an extra life is given when the player finishes the intermission successfully, unless the maximum number of lives are reached.

defaults:
instantlife=true for BD1, BD2, PLCK, false for 1stB, CrLi, BDCFF-native
rewardlife=true for 1stB, CrLi, BDCFF-native, false for BD1, BD2, PLCK

IntermissionSize

Global intermission dimensions. Can be overridden with the Size attribute. Available only in [game] section.

defaults: 40 22 0 0 19 11

Levels

Default number of levels (number, default = 1). Available only in [game] section. XDC supports 1 to 7 levels.

[Level=n1,n2,..,nz]

nx=1..7
All commands in a level section are only executed, when the particular level is played. Can be placed in the [objects] section.
One possible usage is to restrict a [demo] section to a particular level.

Lives

Initial number of lives [maximum number of lives] (numbers, default = 3 9). Available only in [game] section. XDC supports between 3 and 6 lives. The maximum number of lives is hardcoded to 9.

MagicWallProperties

MagicWallProperties.waitforhatching=true|false
MagicWallProperties.convertamoeba=true|false
MagicWallProperties.breakscan=true|false
If waitforhatching=true, the timer does not start befor the guy's hatching, even in case the Magic Wall is activated before this happens.
If convertamoeba=true, the Amoeba will convert to Diamonds the moment a Boulder is dropped into a Magic Wall, placement and state of the Magic Wall or the Amoeba don't matter for this to occur.
If breakscan=true, the engine emulates the buggy timing behavior in BD1 on the C64 which many caves require to work properly. This also has the side effect of converting Amoeba under certain conditions.

defaults:
waitforhatching=true for 1stB, CrLi, false for BD1, BD2, PLCK, BDCFF-native
convertamoeba=true for 1stB, CrLi, BDCFF-native, false for BD1, BD2, PLCK
breakscan=true for BD1 C64, false for all other engines and BDCFF-native

MagicWallTime

Magic wall milling time (one or one number for each level, BDCFF-native default = 999)

Name

Cave (or game) title (string)

PALTiming

For compatibility with PAL versions of home computers. Each second lasts 1.2 times longer than real seconds. (BDCFF-native default = false) If used, BDCFFcompiler multiplies all time values by 1.2, so be aware of roundoff errors.

PenaltyTime

Time discount when a dummy is destroyed. One or one number for each level. (BDCFF-native default = 30)

PushingBoulderProb

Probability normal and with sweet collected. (number [number], BDCFF-native default = 0.25, 1.0)

RandomAlgorithm

For using other than the default algorithm.
For anything related to predictable random. Can be used prior the Attribute or Cave Object using random numbers. Can be C64 or XDC. BDCFF native default is C64.

RandomFill

Pseudo-randomly placed elements (four or less pairs of element name and it's probability). This info is used to pseudo-randomly fill entire field. The predictable random number generator (for cave data)
The used default algorithm is described by Peter Broadribb here: The predictable random number generator (for cave data)
The predictablerandom behavior is influenced by the RandomAlgorithm attribute, ie. the last one set is used.

RandSeed

Random generator seed values for corresponding pseudo-randomly placed elements (one number for each level). -1 means totaly random, ie. different appearance every time the cave starts.

Scrollproperties

Scrollproperties.activeguyscan=true|false
Scrollproperties.counteroverflow=true|false
Scrollproperties.activeguyisfirst=true|false
If activeguyscan=true, the engine looks and remembers the position of a guy in order to scroll to it. If set to false, the engine merely counts the steps and scrolls this far.
If counteroverflow=true, the exact scroll behavior of the C64 is emulated, which has only a singed byte to count the steps and thus can overflow which results in scrolling to the opposite end. This variable is only effective if activeguyscan=false.
If activeguyisfirst=true, the engine looks for the first Inbox/guy to scroll to. If set to false, it scrolls to the last one. If activeguyscan is set to false, this variable is only effective for Inboxes.

A special case is when activeguyscan is set to false and an Inbox is places with a Point object. This overrides the position scan for Inboxes and uses the coordinates of the Inbox which is places last (thus no activeguyisfirst default for BD1 and BD2)

defaults:
activeguyscan=true for 1stB, CrLi, BDCFF native, false for BD1, BD2, PLCK
counteroverflow=true for all C64 engines where applicable, false for BDCFF native
activeguyisfirst=true for 1stB, CrLi, BDCFF native, false for PLCK
mandatory setting in XDC

Selectable

Is selectable (boolean, default value = true). Available only in [cave] section

ShortExplosions

This is for compatibility to different C64 engines.
If set to true, the engine will skip EXPLOSION1 and DIAMONDBIRTH1 starting the sequences right with EXPLOSION2 and DIAMONDBIRTH2.

true for BD1, BD2, PLCK and DAS.
false for 1stB, CrLi.

Size

size=width height [x1 y1 x2 y2]
Dimensions of the cave. If x1, y1, x2, y2 are given, only that part of the cave is visible. Available only in [cave] section. Can range from 20 12 up to 128 128.

default values correspond to game info
XDC supports either 40 22 0 0 39 21, 40 22 0 0 19 11 or 20 12 0 0 19 11. Other sizes between 20 12 and 40 22 will be filled up with InitialBorder by XDC's BDCFF compiler.

SlimePermeability

Slime probability of penetrating (float number). This one is true random. (default=1.0)

SlimePermeabilityC64

permeability
Slime permeability C64 style (number, 8 bit all with equal value). This one is predictable. The predictablerandom behavior is influenced by the RandomAlgorithm attribute, ie. the last one set is used. (one or one number for each level, BDCFF native default = 0)
The seeds can be set with SlimePermeabilityC64.seed and is only effective if this is used after any other pseudo random related objects. -1 means engine default. (one or one number for each level, BDCFF native default = -1)

SlimeProperties

element 1 element 2 [element 1 element 2 [...]]
Slime can take element 1 from above and place element 2 under it.
(default=DIAMOND DIAMONDfd BOULDER BOULDERfd)

WWW

Link to author's webpage

Cave Objects

Add=incx incy search_element add_element [replace_element]

If replace_element is specified, only draw over that element.
incx and incy may be negative numbers.

Addbackwards=incx incy search_element add_element [replace_element]

This is like the regular Add, but works from bottom up.
If replace_element is specified, only draw over that element.
incx and incy may be negative numbers.

BoundaryFill=x y fill_element boundary_element

Sets element in place and fills to the boundary element with a 4-direction algorithm.

FillRect=x1 y1 x2 y2 element [element2]

Filled rectangle of elements

FloodFill=x y fill_element replace_element

Sets element in place and floodfills the replace element with a 4-direction algorithm. If replace_element is not specified, the element at the start coordinates is used.

Line=x1 y1 x2 y2 element

Line of elements
Note that the exact way to draw unsymetrical lines is not decided yet.

Maze=x1 y1 x2 y2 wall_width path_width bias seed_1 [seed_2 .. seed_n] wall_element path_element type [river_factor [braid_percentage]]

The number of seeds is equal to the number of levels.
A seed of -1 means totaly random, ie. different appearance every time the cave starts.
The border is not included. However, any colums and rows at the and which don't fit further path will be filled up with the wall element. (not supported by XDC, so use fitting sizes only).
Unicursal mazes always are drawn with even numbers of paths horizontally and vertically.
If only walls or only path shall be drawn, the unneded element can be NONE, which is a reserved element name for drawing nothing.
bias: a float number whereas 0=vertically biased, 50=neutral, 100=horizontally biased. Works best with a high river factors.
river_factor: a float number whereas 0=many junctions and 100=long paths.
braid_percentage: a float number whereas 0=perfect, 100=full braid, ie. no dead ends.
type can be

perfect: a perfect maze (default)
braid: a maze with no dead ends. Pacman style.
partial_braid: a mix of those two above. Use braid_percentage to specify.
unicursal: without any junctions.

Map=x1 y1 x2 y2 [element] map

Fill a subsection with a map with char codes as in a [map]-section. The map begins in a new line.
If element is given, only draw this element, ie. all other characters are considered background. XDC only supports PLCK elements in maps. If element is used, only 15 of the possible 16 elements can be used in XDC. Width should be a multiple of 2 or the most right column will be padded.

Point=x y element

Single element placed on given position

RandomFill=x1 y1 x2 y2 seed_1 [seed_2 .. seed_n] initial_element element1 probability1 [element2 probability2 [element3 probability3 [element4 probability4]]] [replacement element]

The number of seeds is equal to the number of levels.
A seed of -1 means totaly random, ie. different appearance every time the cave starts.
Initial element can be NONE, which is a reserved element name for drawing nothing.
if replace element is given, it will only be drawn over this.
The predictable random behavior is influenced by the RandomAlgorithm attribute, ie. the last one set is used.

Raster=x y numberx numbery stepx stepy element
Rectangle=x1 y1 x2 y2 element

Outlined rectangle of elements

Cave Elements and Default Map Codes