WLD - WorldBuilder file format
Overview: Morfit’s .wld format can describe any kind of world, and can also describe movement within the world, by:
You can also give physical properties to objects in the world (speed, force,etc.). Everything else must be done through programming. Introduction: The basic building blocks used to build a Morfit world file are: Module: Think of this as a ‘model’. A Module defines a shape. Polygon: That’s just it;a Polygon. Object: An Object is one instance of a predefined shape (model). For example, if you have a module called tree, you can have 100 Objects, placing an instance of a tree in 100 different locations. You can change an Object’s proportions, rotate it, change its location, etc., but the basic shape does not change. Track: A Track defines a path in the world that a Dynamic Object or a Camera can follow. Dynamic Object: Make your Objects dynamic only if you want them to be able to move. A Dynamic Object can be moved either by putting it on a track in the world, or by making it move in a program (using Morfit functions in your code). If you know the object will be stationary, make it a regular Object. Camera: The Camera represents the view from which the world is seen. Animation: Animation is a sequence of bitmaps that replace one another. Background: A Background is a bitmap spread over the background of the world Atmosphere: This sets the atmospheric effects in the world, including light and fog. Test the sample .wld files given , using ‘World Text Editor’ for a better understanding of the Morfit’s world file format. Coordinate System: Morfit .wld coordinate system: positive x = moves out of the screen (away from the world) negative x = moves into the screen (further into the world) positive y = moves to the right in the world negative y = moves to the left in the world positive z = moves up in the world (height) negative z = moves down in the world (height) Example: For an object placed at the origin (0, 0, 0), it's best to place the camera at a positive x location (ex. 500, 0, 0) and give the camera a negative x direction so that it can see the object (ex. —1, 0, 0). Starting Out: Sample: Skeleton.wld Every Morfit ‘.wld’ file must begin with ‘BEGIN DESIGN:’ and end with ‘END DESIGN:’. Module: Sample: Module.wld The fields include: Module Name: Give a name to the module. REMARKS: Every world must include one module named main, which is the engine's starting point. Inside a module, you can have polygons or objects, and nothing else. Recursive definitions are allowed (i.e. a module consisting of an object that uses a module, etc… For example a module called 'house' uses a 'table' object which in turn consists of a 'leg' module….). Polygon: Sample: Polygon.wld The fields include: Polygon Name: Give a name to the polygon. Orientation: Defines the object space. It can be either top, bottom, front, side or not specified. See REMARKS for more details. Color: This button opens a color dialog box. You can choose a color, or customize your own. Bitmap: Give the name of the bitmap to map onto the polygon. Transparent: Any number greater than or equal to —1. -1: Doesn't omit any color. It leaves the image as it is. 0: The most frequently used color is omitted (usually the background color). This is the default. 1: The second most frequently used color is omitted. Etc. Rotated: YES/NO option. If the polygon is rotated, the front of the polygon will always be facing towards the camera, creating the allusion that the polygon is 3-dimensional. Light Diminution: Any number greater than or equal to 0. This controls how fast the polygon blends with the atmospheric color, as it gets further away. For example, you'd give a rock a large value since it should blend into the atmosphere as it gets further away, and you'd give a fire a small value so as to see it even when its far away. With a light diminution value of 0, the polygon won't be influenced by any atmospheric effect. Number of Points: This field will get filled in automatically as you add points to the polygon. Add Points: For each point, you must give six numbers: the first three are the x, y, and z coordinates of the point, the next two are the bitmap x and bitmap y coordinates, and the last number is the point’s light intensity. The bitmap coordinates will be put on the polygon’s x and y coordinates. See REMARKS for examples of matching bitmap points to the polygon points. REMARKS: Orientation: In 'Viewer' mode the orientation is only relevant for dynamic objects. In 'Editor' mode all polygons belong to a certain group, therefore orientation is important. If you want to use functions like Morfit_group_rotate( ) and Morfit_group_move( ) (in 'Object Space'), the engine needs to know the front, top, etc. of each polygon in the group, so that it will know how to advance or rotate it (which polygon should face the camera, which should stay on the ground, etc.). Orientation of polygons go in couples: 1. bottom-top and 2. front-back. For a full definition of the group/dynamic object the polygon belongs to, you must have at least one orientation from each couple. That is, 1. Either a bottom or a top AND 2. Either a front or a back. It is preferable to make the rest of the polygons in the group 'not specified'. If you give the same orientation to more than one polygon, the engine will give that orientation only to the first one it finds. To avoid contradictory cases, give each orientation to one polygon only. When using this together with the "World Builder", it knows how to place a piano (for example) in the world, according to which polygon has the bottom (or top) orientation (i.e. - bottom down or top up). Orientation defines the object space. See the following Morfit functions : Morfit_object_rotate( ) Morfit_object_move( ) Morfit_group_rotate( ) Morfit_group_move( ) NOTE: For beginners, if confused about all these explanations, choose the 'not specified' orientation and don't think too much about it! Bitmap Points: Bitmaps are always a square, with the following coordinates:
Example #1: To specify bitmap coordinates for a triangle, give it these:
Example #2: To tile a bitmap (repetitive bitmap) :
2,3 This will repeat the bitmap 2 across and 3 down to fill the polygon. Example #3: You must specify (at least) 3 bitmap-x and 3 bitmap-y coordinates for a polygon. For all other points it's better to give a —1 value to the bitmap_x and y coordinates, which tells the engine to figure it out by itself. This will avoid contradiction.
0,1 1,1 0,1 1,1 0,1 1,1 You can specify only one coordinate of a point to be —1, if you know the other:
0,1 1,1 Object: Sample: Object.wld The fields include: Module Name: Which module to use. Location: Location of the object. Scale: To change the size of the object. Example: 2, 2, 2 will double the size. .5, .5, .5 will half it. You can change one, two, or all axis. Track: Sample: Track.wld The fields include: Track Name: Give a name to the track. Cyclic: Yes/No option. YES: The track is connected (i.e. after the last point, it continues to the first). Example: A car or an air plane, traversing the same route repetitively. NO: The track is not connected. Example: You want an object to move to the point where the user clicks on the screen. To do this, you take the previous point, and the point where the user clicked, and make a track consisting of those two points. Points: Specify the points in the track (x, y, and z coordinates). Dynamic Object: Sample: DynamicObject.wld (same as Track.wld) The fields include: Object Name: Give the dynamic object a name. Module Name: Which module to use. Type: Relevant in AUTO_BEHAVIOR mode. Car: moves like a car. Plane: moves like an air plane. If in USER_DEFINED mode, the user can use it as he/she wants to. Control: Relevant in AUTO_BEHAVIOR mode. Player: the program takes input from the user. Computer: takes no user input. If in USER_DEFINED_BEHAVIOR mode, the user can use it as he/she wants to. Track: Which track the dynamic object should follow. Relevant only when chase type is 'chase_track' or 'chase_track_airplane'. Track Offset: The center of the track is put at this offset. Chase: Which dynamic object this dynamic object should chase. Only relevant when chase type is 'chase_flexible' or 'chase_location'. Chase Offset: The offset at which the dynamic object should chase the object. Chase Type: chase_track: Movement is according to the track. chase_track_airplane: Like 'chase_track', but moves like an airplane. chase_flexible: Chases softly. chase_location: The dynamic object will change its location, but not its direction. Only the offset is relevant, and not the softness or distance. chase_physics: Uses the 'Physics' fields to determine how to chase. chase_precise: The dynamic object will chase the object precisely — will mimic the object's movements exactly. The object itself won't look like it's moving, but the world around it will. no_chase: Doesn't chase anything. Chase Softness: A number between 0 and 1. This controls how the dynamic object will turn. The bigger this number is, the more rigid (choppy) it'll turn. 0- so smooth, practically not usable. Chase Distance: The distance between this dynamic object and the dynamic object to chase. Physics: Only relevant if chase type is 'chase_physics', except for speed, which is relevant for 'chase_track' or 'chase_track_airplane'. (The following fields are 'physics' fields.) Speed: Specify the speed vector. The direction of the vector is the direction of the movement, and the length of the vector controls the magnitude of the speed (magnitude = the square root of x^2 + y^2 + z^2) For 'chase_track', use the x-coordinate to specify the speed. Example: 100, 0, 0. Force: The direction of the force operating on the vector. The length of the vector controls the magnitude of the force. If you want to implement gravity, make the force something like this: 0, 0, -10. (make z negative). Maximum Speed: The maximum speed it can move. Friction: A number smaller than or equal to 1. 0 : No friction. 1 : Infinite friction, so won't move. Negative numbers: Acts like pressing the gas. This can be used for increasing the speed. —1 doubles the speed. —2 triples the speed. Typical numbers can be .03 or -.03. Camera Name: Give a name to the camera. The first camera the engine sees in the world file will be the default camera. Location: The location of the camera. Direction: The direction the camera is facing. View Field: The angle the camera sees. This number can be anything from 1 to 179 degrees. 1 means a very strong zoom in, and 179 means a very strong zoom out. Culling Depth: -1 : Not active. Other values (in the range of [0-infinity]), will cut the world. For example, if culling depth is 1000, the camera won't see anything further than 1000 virtual units. This makes render work faster since the engine draws less, but a better way of causing this is to use the atmospheric effect: when it's foggy, the engine doesn't have to draw anything in the fog. This is better, since it blends naturally and doesn't cut objects in the middle. Eye Distance: How far from itself the camera should start seeing (can't see things that are too close). The bigger this number is, the more accurate will be the rendering of the objects. On the other hand, a number that is too big will hide objects that are near the camera. Typical numbers are 1, 4, 10, 20 when distance in the world is measured in centimeters. Try to make this number as big as you can, but stop increasing it when near objects are not drawn. (The bigger it is, the better the z-buffer operates and removes 'hidden surface removal' effects.) Track: Which track the camera should follow. Relevant only when chase type is 'chase_track' or 'chase_track_airplane'. Track Offset: The center of the track is put at this offset. Chase: Which dynamic object the camera should chase. Only relevant when chase type is 'chase_flexible' or 'chase_location'. Chase Offset: The offset at which the camera should chase the object. Chase Type: chase_track: Movement is according to the track. chase_track_airplane: Like 'chase_track', but moves like an airplane. chase_flexible: Chases softly, always following the object from behind. chase_location: The camera will change its location, but not its direction (so that if the object turns, you'll see its side or back, because the camera didn't turn). Only the offset is relevant, and not the softness or distance. chase_physics: Uses the 'Physics' fields to determine how to chase. chase_precise: The camera will chase the object precisely - will mimic the object's movements exactly. The object itself won't look like it's moving, but the world around it will. no_chase: Doesn't chase anything. Chase Softness: A number between 0 and 1. This controls how the camera will turn. The bigger this number is, the more rigid (choppy) it'll turn. 0- so smooth, practically not usable. Chase Distance: The distance between the camera and the dynamic object to chase. Physics: Only relevant if chase type is 'chase_physics', except for speed, which is relevant for 'chase_track' or 'chase_track_airplane'. (The following fields are 'physics' fields.) Speed: Specify the speed vector. The direction of the vector is the direction of the movement, and the length of the vector controls the magnitude of the speed (magnitude = the square root of x^2 + y^2 + z^2) For 'chase_track', use the x-coordinate to specify the speed. Example: 100, 0, 0. Force: The direction of the force operating on the vector. The length of the vector controls the magnitude of the force. If you want to implement gravity, make the force something like this: 0, 0, -10. (make z negative). Maximum Speed: The maximum speed it can move. Friction: A number smaller than or equal to 1. 0 : No friction. 1 : Infinite friction, so won't move. Negative numbers: Acts like pressing the gas. This can be used for increasing the speed. —1 doubles the speed. —2 triples the speed. Typical numbers can be .03 or -.03. Elasticity: What happens when the object reaches an obstacle. 1 - the object doesn't lose any speed 0.5 - speed is cut in half 0 — the object stops right there Also, see Mrft_api.h (header file) for an in-depth explanation of all these fields. Animation: Sample:
The fields include: Animation Name: Give a name to the animation. Number of Frames: The number of images the animation has. Times: The time, in hundreds of seconds, in each frame. NOTE: 1. The render function never skips a frame, and therefore you cannot replace the images faster than it takes the engine to render the image. 2. You must give a time for each frame. The next 5 fields are: BACK, BACK-SIDED, SIDE, FRONT-SIDED, and FRONT, representing different angles of the animation. Together, they represent 180 degrees, mirroring the images to get the other half of the circle. You must fill in at least one of these fields. For each of these fields, you specify the bitmap to use for each frame, followed by a number specifying its transparency property. The transparency default is 0 if none is specified. Transparency: -1: Doesn't omit any color. It leaves the image as it is. 0: The most frequently used color is omitted (usually the background color). This is the default. 1: The second most frequently used color is omitted. Etc. Atmosphere: Sample: Atmosphere.wld The fields include: Atmosphere: The RGB (red, green, and blue) values that make up the color of the atmosphere. Fog: Any floating point number between 0 and 2. This number determines the amount of fog in the world. If the dimensions of the world are small, this number should be closer to 0, and if the world is big, this number should be closer to 2. A good starting point is 0.1; work from there. Light: Any floating point number between 0 and 400. This number determines how bright the world should be. Recursive Use of Objects: Sample: Recursive.wld In this sample, the main module consists of one object (round table), which consists of five objects (four legs and a base) , which finally consists of the actual polygons. |
0,0 1,0
0,0 ;1,0 0.5,0 0.5,0
0,1 1,1 0,1 1,1 0,1 1,1
0,0
0,0
1,0 -1,-1 -1,-1