Skyscraper 1.1
Scalable Building Simulator
Building Design Guide
Copyright (C)2005-2007 Ryan Thoryk
This document describes how to create your own buildings for Skyscraper's Scalable Building Simulator engine, and also describes all of the available commands. Please note that the commands and syntax will change frequently during the simulator's development, and formatting will be cleaned up to make the code more readable. A graphical building designer is planned, which will generate these script files based on simplified CAD-like floorplan layouts, and will also allow the user to view the building in 3D as it's being created.
1. Starting a new building
Buildings are stored in text files in Skyscraper's buildings folder, usually at c:\program files\skyscraper\buildings on Windows, or in the "buildings" directory on Unix. The filenames end in BLD, and so you need to make sure your text file ends with ".bld" and not ".txt". To create a new building, first open up a text editor, and read the instructions below. When you're finished, save it into the buildings folder shown above, as something like "mybuilding.bld". The building will appear in Skyscraper's buildings list the next time you run it. You might also want to open one of the buildings that come with Skyscraper ("Triton Center.bld" and "Glass Tower.bld") to get a good idea of the format of a building data file. Eventually there will be a graphical designer app, but it'll be a while since I'm the only developer so far :)
2. General Stuff
1. Comments
To add a comment to your file, simply put the # symbol right
before your comment. For example:
# This is a comment
It's a good idea to use comment markers to add a title header
at the top of your building file. The Triton Center file has this header:
#The Triton Center
#Copyright ©2003-2006 Ryan Thoryk
2. Variables
Variables are marked with percent signs (%), and most system
variables will be described later. There are 256 user variables (0-255) which
can be set using the Set command:
Set 2 = 100
and then can be used later:
Height = %2%
3. IF statements
Basic IF statements can be made, with the following syntax:
if(value1 sign value2)
command
For example, to set the height to 9.5 if the floor number is
less than 82:
if(%floor% < 82) Height
= 9.5
Available signs are = (equals), > (greater than), < (less
than), and ! (is not)
4. Inline calculations
Values can be calculated inline by using the following math
operators:
+ (plus), - (minus), / (divide), and * (multiply).
They can be used anywhere in the data file - here's an example
of one being used with the Set command:
Set 1 = %floorheight% + 10
5. Object parameters from the outside
Information about floors can be obtained outside the floor sections, by referencing the floor in this manner:
Floor(number).parameter
Available parameters are Altitude and FullHeight.
Example:
Set 1 = Floor(5).Altitude
6. Global commands; can be used anywhere in the script
a. CreateWallBox - creates 4 walls (box) at the specified
coordinate locations
Syntax: CreateWallBox destobject,
name, texturename, x1, x2, z1, z2,
height, voffset, tw, th
Example: CreateWallBox external,
My Box, brick, -10, 10, -10, 10, 15, 0, 0, 0
The parameters in this command are very similar to the ones in the AddWall command shown below in the Floor section, except for the destobject parameter.
Destobject can be either external, landscape, buildings, or columnframe (more will come soon). The voffset parameter would then be the altitude offset in feet of the specified destination object's base.
b. CreateWallBox2 - creates 4 walls (box) at
a specified central location
Syntax: CreateWallBox2 destobject,
name, texturename, centerx, centerz, widthx,
lengthz, height, voffset, tw, th
Example: CreateWallBox2 external,
My Box, brick, 0, 0, 10, 10, 15, 0, 0, 0
The parameters are the same as the above command, except that
centerx and centerz define the center of the box, and widthx
and lengthz specify the width and length off of the center.
c. AddCustomWall - creates a custom polygon (wall, floor,
etc) with any number of vertex points. For example, a triangular wall has
3 vertex points, and a standard wall has 4. This function allows 3 or more
vertices.
Syntax: AddCustomWall destobject,
name, texturename, x1, y1, z1, x2, y2, z2, x3, y3, z3, ..., tw, th, revx,
revy, revz
Example: AddCustomWall external,
My Wall, brick, 0, 0, 0, 0, 10, 0, 10, 10, 0, 10, 0, 10, 0, 0, false, false,
false
Revx, revy, and revz are either true or false, and determine if the texture mapping data should be reversed, per axis. If the texture looks strange in the simulator, mess around with the revx and revz values (revy flips the texture upside down).
d. AddShaft - creates a shaft at a specified
location and floor range
Syntax: AddShaft number,
type, centerx, centerz, startfloor, endfloor
Example: AddShaft 1, 2, 10,
10, 0, 9
The number parameter specifies the shaft number to create; type is either 1 for a pipe/utility shaft, 2 for an elevator shaft, and 3 for a stairwell shaft. This command just tells the simulator the area that the shaft will take up, and does not create the actual shaft walls. Later on when you create the walls/floors for the shaft, make sure that you make a floor at the very bottom and very top of the shaft (they can extend beyond the walls).
e. CreateStairwell - creates a stairwell at
a specified location and floor range
Syntax: CreateStairwell number,
centerx, centerz, startfloor, endfloor
Example: CreateStairwell
1, 10, 10, 0, 9
The number parameter specifies the stairwell number to create. This command just tells the simulator the area that the stairwell will take up, and does not create the actual walls.
f. WallOrientation - changes the internal wall
orientation parameter, which is used for determining the wall thickness boundaries
in relation to their coordinates.
Syntax: WallOrientation =
direction
Example: WallOrientation
= left
The direction parameter can either be left, center, or right. Center is default. For example, if center is used, than half of the wall's thickness is to the right (positive) of it's x1/x2 or z1/z2 coordinates, and half is to the left (negative) of the coordinates. If left is used, than the coordinates define the wall's left (negative) edge, and the full thickness is to the right (positive) of those. If right is used, then again the coordinates define the wall's right (positive) edge, and the full thickness is to the left (negative) of those.
g. FloorOrientation - changes the internal
floor orientation parameter, which is used for determining the floor thickness
boundaries in relation to their coordinates.
Syntax: FloorOrientation
= direction
Example: FloorOrientation
= bottom
The direction parameter can either be bottom, center, or top. Top is default. For example, if center is used, than half of the floor's thickness is above (positive) it's x1/x2 or z1/z2 coordinates, and half is below (negative) the coordinates. If bottom is used, than the coordinates define the floor's bottom edge, and the full thickness is the top (positive). If top is used, then again the coordinates define the floor's top edge, and the full thickness is the bottom (negative).
h. DrawWalls - specifies which parts of a wall
or floor should be drawn.
Syntax: DrawWalls = front,
back, left, right, top, bottom
Example: DrawWalls = true,
true, false, false, false, false
The example shown is the default setting. Front is the front polygon (or top if the object is a floor), back is the back polygon (or bottom if a floor), left and right are both the spacing between walls, and top and bottom are also, except top would refer to the back if a floor, and bottom would refer to the front if a floor.
i. ReverseExtents - specifies which parts of
a wall or floor should be drawn.
Syntax: ReverseExtents =
x, y, z
Example: ReverseExtents =
true, false, false
X, y, and z are either true or false, and determine if the texture mapping data should be reversed, per axis. If the texture looks strange in the simulator, mess around with the x and z values (y flips the texture upside down).
7. END command
The End command tells the software to stop processing the current script and start the simulation. This is optional.
3. The Globals Section
The Globals section contains the general information
about your building. The section starts with this header:
<Globals>
and ends with this footer:
<EndGlobals>
Parameters are placed between those two markers, and look like
this:
Parameter = value
Example:
Name = Triton Center
Parameters:
1. Name - building name, required
Example: Name = My Building
2. Designer - name of building's designer,
optional
Designer = Me
3. Location - location of the building, optional
Location = 100 Main Street
4. Description - Brief description of the
building, optional
Description = A really average
building
5. Version - Version of the building (can be text), optional
Version = 1
6. HorizScale - horizontal scaling modifier; default is 1,
optional
HorizScale = 2 (makes
each horizontal foot become 2 feet, keeping vertical feet at the default)
7. CameraAltitude - camera's normal altitude in feet above
the floor, required
CameraAltitude = 3.2
8. CameraFloor - camera's starting floor, starting with 0
(like Floors command), required
CameraFloor = 0
9. CameraPosition - camera's starting position in X (left/right)
and Z (in/out) feet coordinates, required
Syntax: CameraPosition =
X, Z
CameraPosition = 0, -10
10. CameraDirection - direction the camera's facing on startup,
in X (left/right), Y (up down), and Z (in/out) feet coordinates, required
CameraDirection = 0, 10,
28.8
11. CameraRotation - rotation of the camera
on startup, required
CameraRotation = 0, 0, 0
4. The Textures Section
The Textures section loads textures into the simulation and
assigns names to them, for use in the rest of the sections. The section starts
with this header:
<Textures>
and ends with this footer:
<EndTextures>
1. Load - loads a texture
Syntax: Load filename,
name
Example: Load data\brick1.jpg,
Brick
2. LoadRange - loads a numeric range of textures,
and the current number is available in the number variable (%number%)
Syntax: LoadRange startnumber,
endnumber, filename, name
Example: LoadRange 2, 138,
data\floorindicators\%number%.jpg, Button%number%
This example will load the file 2.jpg and name it Button2, 3.jpg as Button3, and so on.
5. The Floor Sections
There are 2 Floor sections available - Floor
and Floors. Floor specifies a single floor, while Floors
specifies a range of floors.
For a single floor, the section would start with this:
<Floor number>
and end with this:
<EndFloor>
For example, a floor section for a lobby would use this:
<Floor 0>
For multiple floors, the section would start with this:
<Floors start
to finish>
and end with this:
<EndFloors>
For example, to work with floors 5-10, you would type:
<Floors 5 to 10>
Floors above ground start with 0 (so a 15-story building would have floors 0-14). Also, floors must be made in the proper order: basement levels must be made first in decending order (-1, -2, -3 etc), and then above-ground floors in ascending order (0, 1, 2, etc).
Variables:
%floor%
- contains the current floor number
%height%
- contains the current floor's ceiling height
%interfloorheight%
- contains the current floor's interfloor height (spacing between floors)
%fullheight%
- contains the current floor's total height, including the interfloor height
Parameters:
1. Name - the name of the current floor, required
Example: Name = Floor %floor%
2. ID - the floor indicator name for the current
floor, such as L (for Lobby), LL (lower level), M (Mezzanine), etc. This is
also used to determine what texture should be loaded for the elevator floor
indicators and floor signs. The texture name would be "Button[ID]"
- so if the ID is 10, the texture name would be "Button10".
ID = %floor%
3. Type - the type of floor the current floor
is. The types are still being defined, but the currently used ones are Basement,
Lobby, Mezzanine, Conference, Office, Service, Skylobby, Hotel, Apartment,
Condominium, Restaurant, Observatory, Recreation, Ballroom, Communications,
and Roof. (Required)
Type = Office
4. Description - description of the current
floor, optional
Description = Offices
5. Height - the floor-to-ceiling height of
the current floor, required
Height = 9.5
6. InterfloorHeight - the height in feet of
the space between floors (below each floor), starting at the floor's altitude,
and ending right below the level's floor; required.
InterfloorHeight = 2.24
7. Group - group floors together. This is a
list of comma-separated floor numbers (or a range specified with the - symbol)
that should be enabled along with this floor when the user arrives at this
floor. For example, if a 2-story room has a balcony, and the room base and
balcony are separate floors, you would specify the other floor's number in
this parameter.
Examples:
Group = 5
Group = 4, 5
Group = 4 - 10
Commands:
1. Exit - exits the current floor section
2. AddFloor - adds a textured floor with the
specified dimensions to the current floor/level
Syntax: AddFloor name,
texturename, thickness, x1, z1, x2, z2,
voffset1, voffset2, tw, th, isexternal
Example: AddFloor My Floor,
brick, 0.5, -10, -10, 10, 10, 0, 0, 0, 0, False
Voffset1 and voffset2 are the height in feet above the current floor's altitude; tw and th are to size/tile the texture (0 lets the app autosize them), and isexternal determines if the floor is part of the building's external framework, or is part of the current floor (is either True or False). Name is a user-defined name for the object.
3. AddWall - adds a textured wall with the
specified dimensions to the current floor/level
Syntax: AddWall name,
texturename, thickness, x1, z1, x2, z2,
height1, height2, voffset1, voffset2,
tw, th, isexternal
Example: AddWall My Wall,
brick, 0.5, -10, -10, 10, 10, 10, 10, 0, 0, 0, 0, False
Height1 is the wall height in feet at the first coordinate set (x1 and z1), and height2 is for the second set (x2, and z2). Voffset1 is the vertical offset in feet (from the floor's altitude) for the first coordinate set, and voffset2 is for the second set. Tw and th are the texture sizing/tiling multipliers, and isexternal determines if the wall is part of the building's external framework (true) or if it's part of the current floor (false).
4. AddInterfloorFloor - adds a textured floor
below the floor of the current floor/level
Syntax: AddInterfloorFloor
name, texturename, thickness, x1, z1, x2,
z2, voffset1, voffset2, tw, th
Example: AddInterfloorFloor
My IFloor, brick, 0.5, -10, -10, 10, 10, 0, 0, 0, 0
The parameters are the same as the AddFloor command, except the voffset values are the height offset in feet above the current floor's altitude, and not above the base floor level.
5. AddInterfloorWall - adds a textured wall
below the floor of the current floor/level
Syntax: AddInterfloorWall
name, texturename, thickness, x1, z1, x2,
z2, height1, height2, voffset1, voffset2,
tw, th
The parameters are the same as the AddWall command, and the voffset values are the same as the AddInterfloorFloor command.
6. AddShaftFloor - adds a textured floor to
the specified shaft, on the current floor
Syntax: AddShaftFloor number,
name, texturename, thickness, x1, z1, x2,
z2, voffset1, voffset2, tw, th
Example: AddShaftFloor 1,
My Floor, brick, 0.5, -10, -10, 10, 10, 0, 0, 0, 0
The parameters are the same as the AddFloor command, and the number value is the shaft number to use
7. AddShaftWall - adds a textured wall to the
specified shaft, on the current floor
Syntax: AddShaftWall number,
name, texturename, thickness, x1, z1, x2,
z2, height1, height2, voffset1, voffset2,
tw, th
The parameters are the same as the AddWall command, and the number value is the shaft number to use. Also, the x1, z1, x2, and z2 parameters are offsets of the shaft's origin (similar to creating elevator walls and floors)
8. AddStairsFloor - adds a textured floor to
the specified stairwell, on the current floor
Syntax: AddStairsFloor number,
name, texturename, thickness, x1, z1, x2,
z2, voffset1, voffset2, tw, th
Example: AddStairsFloor 1,
My Floor, brick, 0.5, -10, -10, 10, 10, 0, 0, 0, 0
The parameters are the same as the AddFloor command, and the number value is the stairwell number to use
9. AddStairsWall - adds a textured wall to
the specified stairwell, on the current floor
Syntax: AddStairsWall number,
name, texturename, thickness, x1, z1, x2,
z2, height1, height2, voffset1, voffset2,
tw, th
The parameters are the same as the AddWall command, and the number value is the stairwell number to use. Also, the x1, z1, x2, and z2 parameters are offsets of the stairwell's origin (similar to creating elevator walls and floors)
10. CallButtonElevators - comma-separated list
of elevators the next created call button set will work with (this must be
specified before CreateCallButtons)
Example: CallButtonElevators
= 1, 2, 3, 4
11. CreateCallButtons - creates a call button
set
Syntax: CreateCallButtons
BackTexture, UpButtonTexture, DownButtonTexture, CenterX,
CenterZ, voffset, direction, BackWidth, BackHeight, ShowBack, tw, th
Example:
Create Marble, CallButtonsTex, CallButtonsTex, -10, 0, 4, right, 0.5,
1, true, 1, 1
BackTexture is the texture of the wall plate behind the buttons
UpButtonTexture and DownButtonTexture are the textures used for the buttons themselves
CenterX and CenterZ are the central location of the call button set object
voffset is the altitude offset that the object is above each floor
direction determines the direction the call buttons
face:
'front' means they face towards the front of the building
'back' means they face towards the back of the building
'left' means they face left
'right' means they face right
BackWidth and BackHeight are the width and height of the wall plate
ShowBack determines if the wall plate should be shown, and is either true or false
tw and th are the texture scaling for the wall plate.
The up and down buttons will be automatically created based on the range of the first specified elevator in the CallButtonElevators command (above).
12. AddStairs - creates a custom staircase
at the specified location.
Syntax: AddStairs number,
name, texture, direction, CenterX, CenterZ, width, risersize, treadsize, num_stairs,
voffset, tw, th
Example: AddStairs 1, TestStairs,
Brick, left, 10, 15, 5, 0.5, 0.5, 10, 0, 0, 0
The direction parameter specifies the direction the staircase faces (where the bottom step is), and so if a staircase goes up from left to right, the direction would be left. Width specifies the step width; risersize specifies the height of each step riser (vertical portion); treadsize specifies the length of each step tread (horizontal portion); num_stairs specifies the total number of steps to create (including the top platform that is level with the above floor, but not including the base platform of the floor below). To calculate the length of the staircase, simply multiply num_stairs with treadsize. To determine the height of the staircase, multiply num_stairs with risersize, and add the voffset value.
6. The External Section
The External section defines parts of the building's exterior. The exterior can also be somewhat created in the Floor sections, but this section provides more options.
Commands:
1. AddTriangleWall - adds a textured triangular
wall
Syntax: AddTriangleWall name,
texturename, x1, y1, z1, x2, y2,
z2, x3, y3, z3, tw, th
Example: AddTrianglewall
My Triangle, brick, 0, 0, 0, 0, 10, 0, 0, 0, 10, 0, 0
2. AddWall - adds a textured wall
Syntax: AddWall name,
texturename, thickness, x1, z1, x2, z2, height1,
height2, altitude1, altitude2, tw, th
Example: AddWall Wall1, brick,
0.5, -10, -10, 10, 10, 15, 15, Floor(2).Altitude, Floor(2).Altitude, 0, 0
The command's parameters are the same as the Floor section's AddWall command, except for the altitudes. Since there is no floor to reference, the actual altitude of the wall in feet must be specified.
3. AddFloor - adds a textured floor
Syntax: AddFloor name,
texturename, thickness, x1, z1, x2, z2,
altitude1, altitude2, tw, th
The command's parameters are the same as the Floor section's AddFloor command, except the altitude parameters. Since there is no floor to reference, the actual altitude of the wall in feet must be specified.
7. The Elevator Section
The Elevator section allows you to create elevators for your building. Elevators are numbered, starting with 1.
The section headers and footers are similar to the ones in the
Floor section.
To specify a single elevator, you would type something like:
<Elevator 1>
and end it with:
<EndElevator>
For a range of elevators, you would use something like:
<Elevators 2 to 10>
and end with:
<EndElevators>
Variables:
%elevator% - number of the current elevator
Parameters:
1. Speed - maximum speed of the elevator, in
feet per second
Example: Speed = 20
2. Acceleration - acceleration speed of the
elevator, in feet per second
Example: Acceleration = 0.015
3. Deceleration - deceleration speed of the
elevator, in feet per second
Example: Deceleration = 0.0075
4. OpenSpeed - open/close speed of the elevator
doors
Example: OpenSpeed = 0.2
5. ServicedFloors - a comma-separated list
of floors this elevator services. Ranges can also be specified by putting
a "-" between the numbers
Example: ServicedFloors =
0, 5, 6, 7-30, 31
6. AssignedShaft - the shaft number this elevator
is in
Example: AssignedShaft =
1
Commands:
1. CreateElevator - creates an elevator at
the specified location
Syntax: CreateElevator x,
y, floor
Example:
CreateElevator 0, 10, 0
X and Y are the coordinates to place the center of the elevator at, and Floor is the floor to place the elevator on.
2. AddFloor - adds a textured floor with the
specified dimensions for the elevator
Syntax: AddFloor name,
texturename, thickness, x1, z1, x2, z2,
voffset1, voffset2, tw, th
Example: AddFloor Floor1,
Wood2, 0.5, -3.5, -3, 3.5, 3, 0, 0, 0, 0
3. AddWall - adds a textured wall for the elevator
Syntax: AddWall name,
texturename, thickness, x1, z1, x2, z2, height1,
height2, voffset1, voffset2, tw,
th
Example: AddWall Wall1, Wood1,
0.5, -3.5, 3, 3.5, 3, 8, 8, 0, 0, 2, 2
The elevator's AddWall command is similar to the other AddWall commands.
4. AddDoors - creates elevator doors
Syntax: AddDoors texturename,
thickness, CenterX, CenterZ, width, height, direction, tw, th
The AddDoors command creates working elevator doors at the central location specified by CenterX and CenterZ, with width and height specifiying the width and height of each door, and Direction specifying the direction that the doors face (currently there are only 2: false if the doors are on the left or right sides, and true if the doors are on the front or back sides)
5. AddShaftDoors - creates shaft elevator doors
Syntax: AddShaftDoors texturename,
thickness, CenterX, CenterZ, tw, th
The AddShaftDoors command creates working shaft elevator doors at the central location specified by CenterX and CenterZ. Other parameters such as width, height, and direction are taken from the AddDoors command (so the regular elevator doors need to be created first). These doors should be moved slightly away from the elevator doors (to separate them both). Also, this command creates doors at all the floors specified in the ServicedFloors value.
6. CreatePanel - creates a button panel
Syntax: CreatePanel texturename,
rows, columns, direction, CenterX, CenterZ, width, height, voffset, spacing,
tw, th
Example:
CreatePanel Wall1, 5,
5, right, -3, -3, 0.5, 1, 4, 0.5, 0, 0
The CreatePanel command creates a button panel at a position relative to the elevator's center position (origin). Rows and Columns define the grid size of the panel. Direction is either "front", "back", "left" or "right", defining which direction the panel faces. Spacing is the space (percent of a button size) between each button.
7. AddFloorButton - creates a floor button
on the panel
Syntax: AddFloorButton texturename,
row, column, floor
The AddFloorButton command creates a floor button on the button panel created with CreatePanel. Row and Column specify the position on the grid where the button should be (the engine also leaves one button-sized space on each side open). Floor specifies the floor number that this button calls.
8. AddControlButton - creates a control button
on the panel
Syntax: AddControlButton
texturename, row, column, type
The AddControlButton command creates a command button on the panel created with CreatePanel. Row and Column are the same as the AddFloorButton command, and Type can be either "open", "close", "cancel", "stop" or "alarm".
9. AddFloorIndicator - creates a floor indicator
Syntax: AddFloorIndicator
direction, CenterX, CenterZ, width, height, voffset
The AddFloorIndicator command creates a floor indicator at the position (relative to the elevator) specified by CenterX and CenterZ. Direction is the direction the indicator faces, and can be either "left", "right", "front" or "back".
8. Small Example Building
To see an example of a small simplistic building in code, look at the Simple.bld file in Skyscraper's buildings directory. It's also available online here.