Bricksets
Contents
The Brick
In the Open Surge Engine, every level is built by using a lot of small pieces called 'bricks'. You can put these bricks together and make them any size that you desire.
The Brickset
A brickset is composed by two elements:
1) The image
No brickset would ever exist without the image where the bricks are contained. This image can be organized in any way you like. Some like their bricks to be spaced, others like to glue them all together to save space (not actual disk space, image space).Both these techniques have positive effects and drawbacks. If you do it "old-school" and create bricksets manually in a text editor, spacing the bricks makes the definition process more human-friendly. On the other hand, gluing all the bricks together and making them stick to a 16*16 grid makes them ready to be defined in Rapid Brickset Editor (RBE for shorts), a method of making these bricksets that will be discussed later.
Also, it is highly suggested that your bricks size be a multiple of 8. (Such as 64 pixels by 32 pixels) Once in the level editor, you can use an 8 x 8 grid that will allow you to put your bricks together in a clean way, and making your bricks fit this grid will save a lot of time and effort in level design.
2) The definition script
The image is where you can see all the artwork for the bricks, but the definition script is how they actually get put into the game for your use.The engine searches a .brk file for references on bricks (found in the themes/ folder), gets their parameters, and the physics take care of the rest once you're done placing bricks in your levels.
This script contains references to the image source(s), how big the bricks are, what part of the image to use as its "face", the angle (for physics processing), the animation sequence (if any), and the property; whether a brick reacts as a plain stepping stone, collapses beneath you once touched, acts as a "cloud" (we will discuss this soon), or moves around in mid-air to make jumping challenges.
Now that you got an image to start, there are two things you can do:
1) Edit an existing .brk and try to define the bricks manually. You may want to do this if you use very few bricks, if you need to add or remove bricks from an existing set, or even if you want to define bricks that RBE can't easily do.
2) Load your image in RBE, and start clicking your way, marking bricks, setting angles and properties, and once you're done furiously clicking every little square with graphics underneath, it exports the scripts for both the brickset and brick groups. Brick groups, just like the name says, are groups of bricks that form larger sections. You can group anything together and make your own prefabs, from rooms, to walkways, walls, ceilings, slope sequences...
TIP: If you build something with your bricks in an empty level and save it, you can then open the level in a text editor, and copy your construction to a group script. It works best if you build starting at x = 0, y = 0.
Let's cover both methods now.
Brick parameters
Overview
A brick is defined like this:
brick 0 { type OBSTACLE behavior DEFAULT angle 0 zindex 0.5 // optional sprite { source_file images/desert1.png source_rect 70 10 128 128 frame_size 128 128 animation { repeat TRUE fps 8 data 0 } } }
Every brick starts with brick followed by its number. Following a sequence is highly advisable, but you can number solids from 1 to 1000 and scenery from 9000 to 9999, for example.
Sprite block
The sprite block is explained in: Sprites.
zindex
Usually a value between 0.0 and 1.0, zindex specifies the order in which bricks are rendered to the screen. Bricks with a large zindex will be displayed in front of others. Bricks with a small zindex will be rendered behind others. Finally, a brick will be drawn behind the player if, and only if, its zindex is lower or equal to 0.5.
This is an optional parameter. If not specified, it defaults to 0.5.
Type
The type will tell the physics core how to handle collisions with this brick.
- OBSTACLE means: a solid brick
- PASSABLE means: you can pass through it (it's a non-solid brick, meaning that it doesn't affect collisions)
- CLOUD means: you can go to the top of it from below (but not the opposite)
Behavior
The behavior specifies the kind of movement the brick will do, if any other than default is specified.
- DEFAULT means: a brick that stands still, with no special behavior. Example:
// a regular brick type OBSTACLE behavior DEFAULT
Note: non-obstacle bricks should have the behavior set to DEFAULT.
- FALL means: the brick will collapse and be destroyed upon being stepped on. Example:
// syntax: behavior FALL horizontal-pieces vertical-pieces // whenever the player steps on the brick, it will collapse into 5 parts, horizontally (and 1 means that the brick is not divided vertically) type OBSTACLE behavior FALL 5 1
- BREAKABLE means: the player can destroy the brick by rolling on it. Example:
// syntax: behavior BREAKABLE horizontal-pieces vertical-pieces // the brick will be broken in 25 pieces (5x5) of equal size type OBSTACLE behavior BREAKABLE 5 5
- CIRCULAR specifies a movable platform. Example:
// syntax: behavior CIRCULAR x-dist y-dist x-speed y-speed initial-phase // x-dist, y-dist mean how wide/tall is the movement of the brick, in pixels // x-speed, y-speed mean how many cycles per second the brick walks. Try setting both to 1. The larger the value, the faster the brick. // initial-phase is a value between 0 and 359, inclusive. You may just set it to zero. // the brick will move horizontally: the trajectory has an amplitude of 100 pixels (to left and to right, meaning that it is 200 pixels wide), and the speed is 1 cycle per second. type OBSTACLE behavior CIRCULAR 100 0 1 1 0
Angle
The angle tells the engine whether this is a ground, wall, ceiling, or slope. 0º is usually flat ground, 90º a right wall, 180º a ceiling and 270º a left wall. Anything in between these values are slopes.
Now, how exactly do you calculate the angle?
How to calculate the angle
One can either calculate the angle manually, or use a computer program to do the computation. Let's see both methods.
Manually: the maths
Suppose you have a slope like this:
To calculate the angle, you use some basic math:
As you can see, the angle is measured from positive x-axis. A plain floor would have 0 degrees. Simple walls/blocks (on which the player can't run through them, vertically) also must have an angle of 0 degrees.
You then write the following code to the .brk file:
// Ramp Piece brick 51 { type OBSTACLE behavior DEFAULT angle 45 sprite { source_file images/desert1.png source_rect 555 60 24 24 frame_size 24 24 animation { repeat TRUE fps 8 data 0 } } }
The corresponding brickset is this (credits to Celdecea):
An Easier Way
Instead of having to write manually the bricksets, one can use automated tools to do most of the job. You may draw your brickset on top of the 16x16 grid displayed below, and then use the Rapid Brickset Editor to generate the .brk script for you. It does all the math for you.
Experience suggests that a good approach is to use the Rapid Brickset Editor to write most of the bricks automatically, but the user should handle manually some more complex bricks (larger than 16x16). For those, it's worth looking the Brickset Editor Tool.