This document provides file format-level documentation for X-Plane 11’s facade file format. The X-Plane facade file format was greatly enhanced with X-Plane 10; X-Plane 8/9 support only type 1 facades without scrapers.
Basic Facade Overview
The facade engine provides several ways to draw a facade, with some combination options:
- A “type 1” facade is a series of walls defined by a rectangular grid of adjacent texture squares – that is, you provide the UV map of the walls. The facade itself is built by extruding the walls up into a prism. This is the only facade option in X-Plane 8 and 9.
- A “type 2” facade has its walls defined by a series of 3-d meshes; the facade is built by warping the mesh (as needed) and placing them adjacent to each other. The result is a prism with 3-d relief. Type 2 facades can also have 3-d objects “attached” to the wall segments; they will be placed along the walls for additional detail.
- Both type 1 and type 2 facades have optional roofs; the type 2 roof can optionally have objects attached to it.
- A facade must be type 1 or type 2 – the features cannot be intermixed.
- A facade can also have a set of OBJs placed in the center. In this mode, the facade provides only a foundation for the structure, and the OBJs are moved up and down to form a telescoping skyscraper. In this mode (“facade-scraper”) the facade is meant to represent street-level building. Either a type 1 or type 2 facade can be promoted to be a facade scraper.
X-Plane 10 introduces two new DSF features for facades:
- A DSF may specify facade walls as bezier curves. This is only allowed for type 2 facades.
- A DSF may specify an exact wall choice for each wall of the facade. If this is done, walls (for a given LOD for type 1 or floor for type 2) are referred to by a zero-based indexing scheme based on their order in the .fac file. In the case where the DSF provides walls, the wall-picking rules and filters are completely ignored and the DSF wall choice is always used.
File Format Structure
Like most X-Plane art assets, a facade is a text file. Unix line endings are preferred, but DOS line endings are still legal. The text encoding must be UTF8. The header consists of
A 1000 FACADE
The version should be 800 for a type 1 facade or 1000 for a type 2 facade.
The rest of the file consists of commands, one per line, that define the facade. Hierarchial structures must occur in consecutive order in the file.
Texturing for the facade are defined by the standard shader syntax; the commands are not duplicated here.
Texture coordinates are defined in pixels. Note that the scale of the texture in pixels is provided directly to X-Plane via a command in the file – it is not read from the actual texture file. This is done for two reasons:
- If X-Plane used the actual texture scale of the texture, then resizing a texture (to improve resolution) would require changing all coordinates in the .fac file. But since the pixels are declared against a virtual texture size, the relative position of art elements is maintained.
- X-Plane loads the facade much earlier than it loads the texture (which is loaded by another core in the background) and thus does not actually know the size of your texture when reading the facade file.
Common Facade Commands
A few commands are common to both type 1 and type 2 facades and apply to the entire facade file.
SHADER_ROOF SHADER_WALL
These commands identify the standard shader commands that follow to apply to the roof or the walls. If neither command is provided, shading commands are assumed to apply to the walls. If no roof shader is provided, the wall shader is used for the roof too.
LAYER_GROUP <offset> <group> LAYER_GROUP_DRAPED <offset> <group>
These commands optionally define the layer that geometry from the facade is bucketed into. The offset is an index (e.g. -1 or +2) and the group name is a standard group name like in the OBJ8 specification.
If the groups are not provided, 3-d geometry goes into the “objects” group and the draped geometry goes into objects – 5.
GRADED RING 0|1
A facade may be draped or graded; in a draped facade, every vertex of the facade’s polygon is individually placed on the terrain; in a graded facade, the center of the first wall is placed on the terrain and the facade is then kept in a flat plane. Graded facades are best for buildings; draped facades are good for fences.
Facades are draped by default; the GRADED directive causes the facade to be graded.
The RING directive takes a 0 or 1 – 1 defines the walls to form a closed ring; 0 means X-Plane does not connect the last facade point to the first. The default is for facades to be rigns; use RING 0 to create fences.
Type 1 Facade Commands
Type 1 facades are hierarchial: a level of detail (LOD) contains several walls; each wall has its own UV map. The sim will pick the best fitting wall definition for each wall of the shape being built.
The following commands apply to an entire type 1 facade:
TEX_SIZE <width pixels> <height pixels>
This defines the size of the texture in pixels, for the purpose of specifying texture coordinates. This directive can be used multiple times and only affects texture coordinates below it.
HARD_WALL <surface> HARD_ROOF <surface>
These commands make the walls and roof of the facade solid for physics collision testing; surface is one of the hard surface types – see the OBJ8 specification for surface types.
DOUBLED 0|1
Normally a facade is made of one-sided geometry. (This can be hacked using the TWO_SIDED shader option.) When DOUBLED 1 is present, the facade is actually extruded twice, with walls facing both inside and outside.
When using DOUBLED 1, do not turn on TWO_SIDED in the shader – doubled creates two one-sided facades. This doubles the geometry count, but it also ensures correct lighting vectors. Doubled is recommended for type 1 facades that are reasonably solid. By default DOUBLED is 0 if not specified in the facade.
FLOORS_MIN <floors> FLOORS_MAX <floors>
New to X-Plane 10.20: these directives put a clamp on the number of floors the facade has. Normally X-Plane attempts to build the number of floors to match the height specified in the DSF. However, if the DSF height is poorly matched to the art asset, the results can look bizarre. (For example, a house might have only a roof, or a sky scraper might have 3000 floors.) These directives, if present, put a clamp on the range of floors that will be built.
If these are not present, the minimum number of floors is 1 and the maximum number will be infinitely large if there are ‘MIDDLE’ tiles to allow for repeating the facade vertically.
Type 1 Facade LOD Commands
Type 1 facades can have multiple definitions for multiple LODs. We strongly recommend that you do not use more than one LOD in a type 1 facade – the framerate savings are very low and the memory costs are very high. Use only one LOD if possible.
LOD <near meters> <far meters>
This defines an LOD. All walls must be in an LOD; the range is the near and far distance at which the LOD will be visible. LODs should occur in order in the file nearest to farthest and have no gaps in the LOD ranges.
ROOF <x pixels> <y pixels>
This command defines a texture coordinate for the roof – when the number of consecutive ROOF commands match the number of vertices in the facade and the facade is a triangle or quad, the coordinates are applied directly. If they do not match, the polygon is scaled over the range defined by a rectangle that should be aligned to the texture X and Y axis and should go lower left, upper left, upper right, lower right.
ROOF_SCALE <left> <bottom> <x> <y> <right> <top> <x_scale> <y_scale>
X-Plane 10 provides an alternate mechanism to specify the UV map of type 1 facades; do not combine this command with the ROOF command. This command takes eight parameters:
- The first six parameters are pairs of pixel x/y coordinates defining a rectangle on the texture by its lower left, then a reference point, and then the upper right.
- The last two parameters define the scale of the texture – x-scale is the number of meters the entire roof texture covers left-to-right, and y-scale is the number of meters the entire roof texture covers bottom-to-top.
When possible, X-Plane will align the reference point with the center of the front of the facade. When this is impossible, X-Plane will move the texture to try to cover the entire building using the specified rectangle at the scale specified. If this is not possible, then the sim will rescale the texture as needed. The texture’s horizontal axis is aligned with the first wall of the facade.
BASEMENT_DEPTH <pixels>
Normally the bottom of a facade wall corresponds with the level ‘ground plane’ of the facade. This command sets the walls to ‘dig in’ to the ground by a certain number of pixels. (The basement depth defaults to 0 if not present.) Use this to provide some underground wall to make a facade look better on sloped terrain.
Type 1 Facade Wall Commands
Each LOD in a facade is made up of one or more wall definitions; X-Plane will pick a random wall definition from all definitions that match the spec needed.
WALL <min width> <max width> [<min heading> <max head>] WALL_RULE <min width> <max width> <min heading> <max heading
The wall command begins a new wall specification. The wall has a set of constraints defining when it ca be used.
- min width and max width are in meters and define the range of walls in X-Plane that this wall definition can cover.
- min heading and max heading define a relative heading to the front of the facade. IN other words, the front of the facade has heading 0, the next wall in a square facade might have heading 90, etc. This lets you differentiate walls that face forward from side or back walls. The min/max heading is optional.
- All headings should be in degrees, e.g. 0->359. To make a wall face any heading use 0 0 for the min and max.
The WALL_RULE command adds a second set of conditions to the previously specified wall; the wall will be used if any of the rules match.
SCALE <meters per texture x> <meters per texture y>
The scale command defines the scale of the albedo texture used for walls – it is the number of meters the entire texture would fill horizontally, then vertically. The SCALE command must be specified for each wall, even if all walls use the same scale.
ROOF_SLOPE <degrees> [SLANT]
Optionally, the ROOF_SLOPE command causes the top-most set of quads in the wall to ‘bend over’. DEGREES is the number of degrees to use to bend the wall over.
If the SLANT directive is present, the quads that are ‘bent over’ will become less tall and the texture will not be distorted. If SLANT is not present, the texture is stretched as its top moves inward. SLANT is more useful for creating textures, but non-SLANTED behavior matches X-Plane 8 and 9.
BOTTOM t1 t2 MIDDLE t1 t2 TOP t1 t2 LEFT s1 s2 CENTER s1 s2 RIGHT s1 s2
These commands define the UV map (texture coordinates) of the facade wall. “s” coordinates are in horizontal pixels, “t” coordinates are in vertical pixels. There are a few requirements:
- Commands should be listed in order, e.g. all bottoms, then all middles, then all tops, then all lefts, then all centers, then all rights. (The left/center/right sequence may optionally come before the bottom/middle/top sequence.)
- All coordinates must be adjacent, e.g. each “next” tile’s left or bottom coordinate must be the same as the previous tile’s right or top coordinate – no gaps!
- All facades should contain at least one horizontal and one vertical tile.
The sim allocates tiles starting at the ‘outside’, alternating bottom/left and right/top tiles. Once the entire texture has been used, center/middle) tiles may be repeated (in consecutive order starting from the first one specified to provide arbitrarily long/tall walls.
Type 2 Facade Commands
These commands are only used in type 2 facades and apply to the entire facade.
OBJ <file_path>
This imports an OBJ model into the facade. Objects are referenced within the facade using a zero-based index, based on the order of the OBJ commands. The file path is relative to the facade’s parent folder.
ROOF_SCALE <meters x> [<meters y>]
This defines the scale of the roof texture – the texture is applied so that each copy of the texture takes meters_x meters horizontally and meters_y vertically. If meters_y is not included, the texture is treated as square.
NO_WALL_MESH NO_ROOF_MESH
New to X-Plane 11.10: These commands disable rendering of the wall and roof triangles, while leaving attached objects in place. They are significantly more efficient (but have the same net effect) as using a completely transparent wall and/or roof texture. Each command can be used on its own or in combination with the other.
When you use NO_WALL_MESH you are still required to provide some kind of “dummy” wall mesh for type 2 facades – a simple rectangle will suffice. The rectangle is used to compute the metrics of the wall segment for spelling/fitting.
When using the no-mesh commands, you can leave the shaders blank to get a default gray shader – this minimizes resources used by X-Plane.
Type 2 Facade Floor Commands
Type 2 facades have multiple “floors”, but the name is misleading. Each “floor” of the facade is actually a complete facade definition designed to appear to have a certain number of floors. In other words, if your facade can have 1, 2, or 3 floors, you provide 3 complete facade definitions, for a 1-story, 2-story, and 3-story building in the style you are aiming to create.
(The assumption behind this scheme is that type 2 facades are meant for airports, where the architectural changes caused by adding/removing floors are significant enough that floors cannot be “stacked” as individual units.)
The particular floor rendered is picked by X-Plane by picking the floor whose top-most roof height best matches the requested height in the DSF.
FLOOR <name>
This defines a new floor definition; the name is unused by the simulator and is present only for debugging purposes.
ROOF_HEIGHT <height>
This defines the height of the roof in meters for this facade. Type 2 facades can have multiple roofs rendered; list them from lowest to highest.
If a roof height is set to 0, the roof is draped over the terrain and will use the draped layer group (from above). This can be used to create ground floors for parking structures.
TWO_SIDED_ROOF
This sets the previous roof (to have two-sided rendering; the default is to only be rendered on one side.
HARD_ROOF <surface>
This sets the hard surface type for collision testing for all roofs in this floor.
ROOF_OBJ <index> <s> <t> [<lo> <hi>] ROOF_OBJ_HEADING <index> <s> <t> <r> [<lo> <hi>]
These commands add an object to the roof previously declared with ROOF_HEIGHT. The index is the index of the OBJ command in the facade file to specify which model is picked. S and T are the pixel positions of the objects on the roof.
In X-Plane 10.20, the ROOF_OBJ_HEADING command lets you specify a heading of the object, relative to the front of the facade, in degrees.
In X-Plane 10.20 and later, optionally a pair of numbers indicates the setting at which this OBJ will be drawn; legal values are 1-6 and match the “object density” setting in X-Plane. The probability of the object appearing increases among the range; in other words, if an object has a range of 2 4 then the object will never be present at rendering setting 1, will appear rarely at setting 2, somewhat at setting 3, and will always be present at settings 4, 5, and 6.
Type 2 Facade Segment Commands
Within a given “floor” (that is, height variant) of a type 2 facades, one or more segments must be defined. The segments are lego brick meshes that are mixed and matched to create walls.
Each segment comes in two variants: the regular segment is used when the wall is flat, and the SEGMENT_CURVED segment is used when the wall is a bezier curve. Curved walls are created by ‘bending’ the mesh, so a higher tessellation rate on the curved segment will create a smoother look; two types of segments are provided to optimize down vertex count on flat walls.
SEGMENT <optional debug index number> SEGMENT_CURVED <optional debug index number>
These commands begin the definition of a new segment for this floor – segments are referred to by zero-based index numbers. There should be one SEGMENT_CURVED for each SEGMENT directive.
ATTACH_GRADED <index> <x> <y> <z> <heading> [<lo> ,hi>] ATTACH_DRAPED <index> <x> <y> <z> <heading> [<lo> ,hi>]
These commands add an object to a segment. The index refers to the OBJ directive to name the model. X, Y and Z are the position of the object in meters relative to the segment itself. Heading defines the orientation of the object relative to the wall being placed. (That is, a north-facing object will face out from the wall if heading is 0.)
If lo and hi are present, they are the rendering setting levels at which this OBJ is added – see ROOF_OBJ for the numbering scheme.
ATTACH_GRADED places the object exactly at X,Y, Z; ATTACH_DRAPED places the object at this location and then drops it down until the object’s reference point contacts the terrain mesh.
MESH <group> <far LOD> <cuts> <vertex_count> <idx_count>
Each segment consists of one or more meshes. Multiple meshes provide two types of flexibility for authors:
- Each mesh can have its own far LOD distance, after which it is not drawn. This lets the author eliminate high-vertex-count details.
- Meshes are always drawn in group order within a single facade and LOD. Thus it is possible to ensure that a facade’s “insides” are drawn before the glass windows by putting the solid interior in group 0 and the windows in group 1.
Note: group order is not maintained between meshes that have different LODs! To create a detailed scene inside a facade with glass windows, put the detailed scene in an attached object and set the object’s layer group to objects – 1 to ensure drawing before the facade. This technique has the advantage of being much more efficient for vertex count, and fast for frame-rate as long as the object is instance-friendly.
Vertex groups should be consecutively numbered starting at 0. The far LOD is in meters.
Divisions defines the approximate number of subdivisions in the mesh for the purpose of bending it when a wall is curved. In other words, if your wall is made of four quads horizontally, set divisions to 4.
The mesh pre-declares the number of vertices and indices making up its mesh.
VERTEX <x> <y> <z> <normal x> <normal y> <normal z> <texture s> <texture t
After the MESH command, each vertex is declared on one line using the VERTEX command. Positions are in meters, normals should be normalized, and texture coordinates are in fractional ratios – in other words, the format is just like the VT command in an object.
In a facade wall, a wall runs along the positive X direction, with the outside of the wall facing the positive Z direction and the positive Y direction going up. The origin (0,0,0) is placed at the beginning of the wall on the ground.
IDX <list of indices>
The mesh is made of triangles – the IDX directive takes 1 or more integer indices (a zero based reference to the above vertices) to define the triangles. (Unlike the OBJ file format, the IDX directive can take a variable number of indices.
Type 2 Facade Wall Commands
In a type 2 facade, a wall is defined by combinations of the segments defined above. The intention is to model a number of different wall looks using a reasonably small number of segments (because each segment is a full mesh and thus time consuming to author).
While type 1 facades mix and match the quad wall panels via a strict algorithm, the ordering of segments in a type 2 facade wall is specified by the author in the form of a list of spellings. Each spelling indicates a series of segments to include in a specific order. Typically a wall will have several spellings to provide a way to build the wall at differing lengths.
WALL <min width> <max width> <min heading> <max heading> WALL_RULE <min width> <max width> <min heading> <max heading
The WALL command defines a new wall within the floor, for which spellings may be specified. The width and heading constraints are the same as in a type 1 facade – see the type 1 facade WALL command for more info.
In X-plane 10.20 an optional WALL_RULE can be added to add a second condition for using the wall; if any wall rule meets the wall, it may be used.
Given multiple walls that fit a particular scenario, the sim will pick one randomly. Given multiple spellings that roughly fit a particular scenario, the sim will pick one randomly.
SPELLING <list of segment index numbers>
The spelling command adds a new spelling to the previously specified wall. Each index in the spelling refers to a SEGMENT from the current floor.
Spellings can be included in any order; it is recommended that enough spellings be included to cover the entire range of widths that the wall rule allows. If the wall is too long for even the longest spelling, spellings will be repeated; if it is too short the smallest spelling is used.
The ‘gap’ between the length of the spelling and the length of the wall needed in X-Plane is overcome by stretching or squishing the spellings. Therefore two practices are recommended for spellings:
- Include a lot of length variants to avoid stretching and squishing. The more variants and choices the sim has, the less it has to squish.
- Prefer using longer segments to more segments for efficiency.
Facade Scraper Commands
Both type 1 and type 2 facades can include facade scraper commands; the facade “becomes” a facade scraper when these commands are present. Note that the facade scraper definition is only used when the requested height of the facade matches a facade scraper definition in the .fac file.
Each facade can contain zero or more facade scraper definitions – a facade scraper definition defines a height range for which 3-d OBJ models are to be used.
For each facade scraper, one or more sets of model choices can be specified – the model choices come with “pins” that indicate the area that must be in the facade to sanely use the model.
The intention is to use multiple facade scrapers to handle radically different height ranges (if desired) and to use different model sets within a facade scraper for buildings with narrow vs. wide foot-prints. Facade scraper models are taken in a first-fit manner, so it is recommended that you put your largest models first.
FACADE_SCRAPER <min AGL> <max AGL> <floor increment> <base facade floors>
This defines a facade scraper to be used when the DSF requested facade height is between min-agl and max-agl meters.
Floor increment provides a rounding in meters for the distance the tower object can be moved up and down from its lowest position; this ensures that you will not see half of a floor.
When the facade scraper is used, the regular type 1 or type 2 facade definition will use base facade floors as its height and not the DSF decalred height.
FACADE_SCRAPER_MODEL <base file> <tower file> <pins>
This defines one “model set” for a given facade scraper. Based file and tower file are OBJs that are specified by relative path of the facade file’s parent folder.
The base model is placed at the center of the first side of the facade, on the ground. The tower file is placed at the same location when the facade is in its minimum-AGL configuration; as the AGL is increased, the tower object moves upward in increments of “floor increment”.
The pins are a variable length list of X/Z coordinate pairs (in the space of the base object). If any “pin” is outside of the facade boundary, this model will not be used. Thus the pins provide a way to guarantee that critical points of the tower are inside the facade itself.
The tower model is optional – use the string “-” to specify no tower.
FACADE_SCRAPER_MODEL_OFFSET <delta x> <delta z> <delta heading> <base file> <low rendering> <high rendering> <delta x> <delta z> <delta heading> <tower file> <low rendering> <high rendering> <pin list>
Note: this command takes all of its arguments on one line; the syntax is split here only for readability.
Starting in X-Plane 10.20, the much more verbose FACADE_SCRAPER_MODEL_OFFSET command can be used to specify a scraper model with additional customization.
- The delta x, delta z, and delta heading commands offset the models from the position they would normally have using FACADE_SCRAPER_MODEL. The first set of offsets apply to the base, the second to the tower.
- The low and high values are integer rendering settings at which to bring in this model – see ROOF_OBJ for the numbering scheme. The first offsets are for the base, the second for the tower.
FACADE_SCRAPER_PAD <x> <y> <z> <rotation> <model file> [<low> <high>]
In X-Plane 10.20 a third object can be added to the preceding FACADE_SCRAPER_MODEL[_OFFSET] command. The object is located at the same location as the tower, plus the offsets specified by delta x, delta y, delta z, and delta r. If lo and hi are present, they are integer rendering setting levels for showing the object.
Revision History 9/5/17 Added no-mesh directives for XP11.10.