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.