-
Notifications
You must be signed in to change notification settings - Fork 5
FEZLVL file format
.fezlvl files contain level data stored in JSON format. This documentation presents a structure and purpose of each property in this file format. Descriptions are incomplete in some cases, and they might be incorrect due to lack of proper testing in the game itself, but that'll improve over time.
This format differs a little bit from how the level data is arranged in the game's structure in order to eliminate redundant and unnecessary data arrangement. Here's a list of all differences:
-
Level's
Trilesproperty is a list of TrileInstances instead of a dictionary with TrileEmplacement keys, which are now stored within TrileInstance asPositionproperty. -
OverlappedTrilesproperty of TrileInstance has been removed. All overlapped triles are stored in Level'sTrileslist. - TrileGroup stores a list of TrileEmplacements instead of an exact replica of a TrileInstance structure.
- Scripts have been completely changed to be stored in a more efficient syntax.
Top-level object stored in .fezlvl JSON file.
| Property name | Type | Description |
|---|---|---|
| Name | String | Name of the level used internally by the game. |
| NodeType | LevelNodeType | Type of node used to represent level on the map. |
| Size | Vector3 | Size of the map. |
| StartingPosition | TrileFace | Default location and orientation where player should start the level. The location has to point to an existing trile instance. |
| Flat | Boolean | If true, blocks player's ability to shift in this level. |
| Quantum | Boolean | If true, blocks are visually randomized. |
| Descending | Boolean | Behaviour currently unknown. Used only in ZU_CODE_LOOP. |
| Loops | Boolean | If true, level loops vertically. |
| Rainy | Boolean | Determines whether it should rain in the level. |
| BaseDiffuse | Float | Scale of a diffuse lighting. |
| BaseAmbient | Float | Scale of an ambient lighting. |
| SkyName | String | Name of a sky asset to use in this level. |
| SkipPostProcess | Boolean | If true, level is rendered without post-processing effects. |
| GomezHaloName | String | A name of a background plane texture used for halo effect around Gomez. |
| HaloFiltering | Boolean | Behaviour currently unknown. |
| BlinkingAlpha | Boolean | Behaviour currently unknown. |
| WaterHeight | Float | Height of water in this level. |
| WaterType | LiquidType | Type of liquid to use for water in this level. |
| SongName | String | Name of the song to play. |
| MutedLoops | String[] | List of names of loops to mute in played song. |
| AmbienceTracks | AmbienceTrack | List of ambience tracks to play. |
| SequenceSamplesPath | string | Behaviour currently unknown. |
| LowPass | Boolean | If true, music is put through low pass filter. |
| FAPFadeOutStart | Integer | Far Away Place fade out start. Unused. |
| FAPFadeOutLength | Integer | Far Away Place fade out length. Unused. |
| TrileSetName | String | A name of a Trile Set to use in this level. |
| Triles | TrileInstance[] | A list of triles in this level. |
| Groups | TrileGroup[] | A list of trile groups. |
| Volumes | Volume[] | A list of volumes in this level. |
| Scripts | Script[] | A list of scripts in this level. |
| ArtObjects | ArtObjectInstance[] | A list of art object instances in this level. |
| BackgroundPlanes | BackgroundPlane[] | A list of background planes in this level. |
| Paths | MovementPath[] | A list of paths in this level. |
| NonPlayerCharacters | NpcInstance[] | A list of NPCs in this level. |
All enums are stored as PascalCamelCase string parameters.
Enum specifying how level should appear in the map. It can take one of three values:
- Node
- Hub
- Lesser
Geometry structure containing X, Y and Z coordinates. It's stored as an array of three floating point numbers, simirarly to how GeoJSON does it.
Structure identifying location of a trile and facing direction. In FEZLVL data, it's used only to determine a default starting position.
| Property name | Type | Description |
|---|---|---|
| Id | TrileEmplacement | Location of the trile. Has to point to an existing trile instance. |
| Face | FaceOrientation | Facing orientation. For starting position, it can be only Left, Right, Back or Front |
Geometry structure containing X, Y, and Z coordinates of a trile in the map. It's stored as an array of three integer numbers.
Enum specifying one of six possible trile face orientations - Left, Down, Back, Right, Top or Front.
Enum specifying one possible water types used in levels - None, Water, Blood, Lava, Sewer, Purple or Green.
Structure specifying the name of ambience track to play and when it's played.
| Property name | Type | Description |
|---|---|---|
| Name | String | Name of an ambience track to play. |
| Day | Boolean | If true, ambience track will play during the day. |
| Dusk | Boolean | If true, ambience track will play during the dusk. |
| Night | Boolean | If true, ambience track will play during the nigty. |
| Dawn | Boolean | If true, ambience track will play during the dawn. |
Structure containing information about a single trile - a level tile in 3D space. Multiple triles may be present in the same position.
| Property name | Type | Description |
|---|---|---|
| Emplacement | TrileEmplacement | Location of the trile instance in 3D grid. Used as identifier. |
| Position | Vector3 | Real position of this trile instance in 3D space. Can be used to offset the block. |
| Phi | Byte | Rotation of this trile instance. Each increment is 90 degrees counter-clockwise. |
| Id | Integer | ID of a trile in Trile Set used by this level. |
| Settings | TrileInstanceActorSettings | Additional parameters of this trile. Can be null. |
Structure containing additional information of a trile instance.
| Property name | Type | Description |
|---|---|---|
| ContainedTrile | int | Behaviour currently unknown. Can be null. |
| SignText | String | Language identifier of a text which appears when interacting with this trile. |
| Sequence | String | Behaviour currently unknown. Presumably related to blinking blocks. |
| SequenceSampleName | String | Behaviour currently unknown. Same as above. |
| SequenceAlternateSampleName | String | Behaviour currently unknown. Same as above. |
| HostVolume | Integer | ID of host Volume. Purpose unknown. |
Structure containing a list of trile instances grouped together and parameters of this group.
| Property name | Type | Description |
|---|---|---|
| Triles | TrileEmplacement[] | List of coordinates used to determine which trile instances belong to this group. |
| Path | MovementPath | Path this group moves along |
| Heavy | Boolean | Behaviour currently unknown. |
| ActorType | ActorType | Type of actor this group should be treated as. |
| GeyserOffset | Float | Behaviour currently unknown. |
| GeyserPauseFor | Float | Behaviour currently unknown. |
| GeyserLiftFor | Float | Behaviour currently unknown. |
| GeyserApexHeight | Float | Behaviour currently unknown. |
| SpinCenter | Vector3 | Behaviour currently unknown. |
| SpinClockwise | Boolean | Behaviour currently unknown. |
| SpinFrequency | Float | Behaviour currently unknown. |
| SpinNeedsTriggering | Boolean | Behaviour currently unknown. |
| Spin180Degrees | Boolean | Behaviour currently unknown. |
| FallOnRotate | Boolean | Behaviour currently unknown. |
| SpinOffset | Float | Behaviour currently unknown. |
| AssociatedSound | String | Behaviour currently unknown. |
Structure defining the path of movement and its properties. It's used by Trile groups and occasionally by functions available through Scripts.
| Property name | Type | Description |
|---|---|---|
| Segments | PathSegment[] | A list of path segments defining the path. |
| NeedsTrigger | Boolean | If true, the path needs to be triggered to function. |
| EndBehavior | PathEndBehaviour | Defines how path should behave when end is reached. |
| SoundName | String | A name of sound to use when path is in use. |
| IsSpline | Bool | If true, path uses spline interpolation. |
| OffsetSeconds | Float | Determines how long to wait until movement starts. |
| SaveTrigger | Boolean | Behaviour currently unknown. |
Structure defining properties of a path segment.
| Property name | Type | Description |
|---|---|---|
| Destination | Vector3 | Destination of this path segment. |
| Duration | Float | Time it takes to traverse the segment, in seconds. |
| WaitTimeOnStart | Float | Time to wait on start of the segments, in seconds. |
| WaitTimeOnFinish | Float | Time to wait on end of the segment, in seconds. |
| Acceleration | Float | Acceleration factor. Exact behaviour currently unknown. |
| Deceleration | Float | Deceleration factor. Exact behaviour currently unknown. |
| JitterFactor | Float | Jittering factor. Exact behaviour currently unknown. |
| Orientation | Quaternion | Behaviour currently unknown. |
| CustomData | CameraNodeData | Contains additional camera data. Can be null. |
Geometry structure containing X, Y, Z and W coordinates. It's stored as an array of four floating point numbers, simirarly to how GeoJSON does it.
Structure containing custom information about camera movement along path.
| Property name | Type | Description |
|---|---|---|
| Perspective | Boolean | Behaviour currently unknown. |
| PixelsPerTrixel | Integer | Behaviour currently unknown. |
| SoundName | String | Behaviour currently unknown. |
Enum specifying how path segment should end - Bounce, Loop or Stop.
Enum specifying a type of actor used by TrileGroup, Art Object or Background Plane. Depending on a type of actor, specified object can be treated differently. A list of all actor types along with their behaviours will be provided in the future.
Structure defining a cuboid zone with custom properties. These zones can also be used by Scripts for custom conditions or triggers.
| Property name | Type | Description |
|---|---|---|
| Orientations | FaceOrientation | Orientations towards which perspective can be shifted for this Volume to work. |
| From | Vector3 | Coordinates of one of the corners of this volume zone. |
| To | Vector3 | Coordinates of another of the corners of this volume zone. |
| ActorSettings | VolumeActorSettings | Settings of this volume instance. |
Structure defining settings for a volume instance.
| Property name | Type | Description |
|---|---|---|
| DotDialogue | DotDialogueLine[] | List of Dot dialogues used by this volume. |
| CodePattern | CodeInput[] | Input combo used by this volume. |
| IsBlackHole | Boolean | Exact behaviour currently unknown. |
| NeedsTrigger | Boolean | Behaviour currently unknown. |
| IsSecretPassage | Boolean | Behaviour currently unknown. |
| WaterLocked | Boolean | Behaviour currently unknown. |
| IsPointOfInterest | Boolean | Behaviour currently unknown. |
| FarawayPlaneOffset | Vector2 | Behaviour currently unknown. |
Structure defining Dot dialogue.
| Property name | Type | Description |
|---|---|---|
| ResourceText | String | Behaviour currently unknown. |
| Grouped | Boolean | Behaviour currently unknown. |
Enum specifying in-game input - None, Up, Down, Left, Right, SpinLeft, SpinRight or Jump.
Geometry structure containing X and Y coordinates. It's stored as an array of two floating point numbers, simirarly to how GeoJSON does it.
Structure defining custom behaviour which can await certain triggers, react to specified conditions and execute defined actions with given parameters.
| Property name | Type | Description |
|---|---|---|
| Name | String | Name of the script. Presumably unused. |
| Timeout | Boolean | A time after which the script should be terminated, in seconds. |
| Triggers | ScriptTrigger[] | A list of triggers this script can react to. |
| Conditions | ScriptCondition[] | A list of conditions that has to be met for this script to be executed. |
| Actions | ScriptAction[] | A list of actions this script will execute. |
| OneTime | Boolean | If set, this script will execute only once. |
| Trigerless | Boolean | Behaviour currently unknown. |
| IgnoreEndTriggers | Boolean | Behaviour currently unknown. |
| LevelWideOneTime | Boolean | Behaviour currently unknown. |
| Disabled | Boolean | If set, this script will be disabled until enabled by another script. |
| IsWinCondition | Boolean | Behaviour currently unknown. |
ScriptTrigger, ScriptCondition and ScriptAction are using string-encoded operations. Their syntax may vary, but they will always start with entity identifier followed by a dot. Entity identifier is simply its class name. If an entity is not static (like Level or Camera), it's followed by a square brackets [] operator containing an ID of an object (like Volume or ArtObject).
A full list of entities and their exposed triggers, properties and actions will be provided in the future.
String-encoded operation starting with entity identifier, followed by the name of the trigger, like so:
[EntityIdentifier].[TriggerName]As an example:
Level.StartString-encoded operation starting with entity identifier, followed by the name of the property, one of the valid comparison operator (==, >=, <=, >, < or !=) and value literal, like so:
[EntityIdentifier].[Property] [ComparisonOperator] [ValueLiteral]As an example:
Gomez.CollectedCubes >= 1Game.GetLevelState == INTRO_COMPLETEString-encoded operation starting with entity identifier, followed by the name of the action and a list of parameters enclosed by parentheses and separated by commas. Additionally, operation string can be preceded by two control characters:
-
#- blocks execution of following actions until this one is completed. -
!- terminates the entire script once the action is executed.
Script action has following syntax:
[ControlCharacters][EntityIdentifier].[ActionName]([Property1], [Property2], ...)As an example:
Game.Wait(1)#Dot.Say(DOT_CUBES_GET_A, False, False)Structure defining art object instance, its location and settings.
| Property name | Type | Description |
|---|---|---|
| Name | String | Name of the art object used by this instance. |
| Position | Vector3 | Position of this instance. |
| Rotation | Quaternion | Rotation of this instance. |
| Scale | Vector3 | Scale of this instance. |
| Scale | Vector3 | Scale of this instance. |
| ActorSettings | ArtObjectActorSettings | Settings of this art object instance. |
Structure defining settings for art object instance.
| Property name | Type | Description |
|---|---|---|
| Inactive | Boolean | If set, this Art Object will be inactive by default. |
| AttachedGroup | Integer | Identifier of a Trile Group this art object belongs to. Can be null. |
| RotationCenter | Vector3 | Rotation center of this art object. |
| SpinView | Viewport | Behaviour currently unknown. |
| SpinEvery | Float | Behaviour currently unknown. |
| SpinOffset | Float | Behaviour currently unknown. |
| OffCenter | Boolean | Behaviour currently unknown. |
| VibrationPattern | VibrationMotor[] | Behaviour currently unknown. |
| CodePattern | CodeInput[] | Behaviour currently unknown. |
| Segment | PathSegment | Behaviour currently unknown. |
| NextNode | Integer | Behaviour currently unknown. Can be null. |
| DestinationLevel | String | Behaviour currently unknown. |
| TreasureMapName | String | Behaviour currently unknown. |
| InvisibleSides | FaceOrientation[] | Behaviour currently unknown. |
| TimeswitchWindBackSpeed | Float | Behaviour currently unknown. |
| ContainedTrile | ActorType | Behaviour currently unknown. |
Enum specifying controller vibration - None, LeftLow or RightHigh.
Enum specifying viewport - None, Front, Right, Back, Left, Up, Down or Perspective.
Structure defining background plane, its location and properties.
| Property name | Type | Description |
|---|---|---|
| Position | Vector3 | Position of a background plane. |
| Rotation | Quaternion | Rotation of a background plane. |
| Scale | Vector3 | Scale of a background plane. |
| Size | Vector3 | Behaviour currently unknown. |
| TextureName | String | Name of a texture used by this background plane. |
| LightMap | Boolean | Behaviour currently unknown. |
| AllowOverbrightness | Boolean | Behaviour currently unknown. |
| Filter | Color | Behaviour currently unknown. |
| Animated | Boolean | Behaviour currently unknown. |
| Doublesided | Boolean | Behaviour currently unknown. |
| Opacity | Float | Behaviour currently unknown. |
| AttachedGroup | Integer | A Trile Group this background plane belongs to. Can be null. |
| Billboard | Boolean | Behaviour currently unknown. |
| SyncWithSamples | Boolean | Behaviour currently unknown. |
| Crosshatch | Boolean | Behaviour currently unknown. |
| UnusedFlag | Boolean | Behaviour currently unknown. |
| AlwaysOnTop | Boolean | Behaviour currently unknown. |
| Fullbright | Boolean | Behaviour currently unknown. |
| PixelatedLightmap | Boolean | Behaviour currently unknown. |
| XTextureRepeat | Boolean | Behaviour currently unknown. |
| YTextureRepeat | Boolean | Behaviour currently unknown. |
| ClampTexture | Boolean | Behaviour currently unknown. |
| ActorType | ActorType | Behaviour currently unknown. |
| AttachedPlane | Integer | Behaviour currently unknown. Can be null. |
| ParallaxFactor | Float | Behaviour currently unknown. |
Structure containing information about R, G, B and A components of the color. It's stored as a HTML color code (#rrggbbaa) in a string.
Structure defining an instance of a non-playable character in the level.
| Property name | Type | Description |
|---|---|---|
| Name | String | Name of an NPC to use for this instance. |
| Position | Vector3 | Initial position of this NPC instance. |
| DestinationOffset | Vector3 | Behaviour currently unknown. |
| WalkSpeed | Float | Behaviour currently unknown. |
| RandomizeSpeech | Boolean | Behaviour currently unknown. |
| SayFirstSpeechLineOnce | Boolean | Behaviour currently unknown. |
| AvoidsGomez | Boolean | Behaviour currently unknown. |
| ActorType | ActorType | Behaviour currently unknown. |
| Speech | SpeechLine[] | Behaviour currently unknown. |
| Actions | NpcAction Dictionary | Behaviour currently unknown. |
Structure defining a speech line and its additional attributes.
| Property name | Type | Description |
|---|---|---|
| Text | String | Language identifier of a text which is used. |
| OverrideContent | NpcActionContent | Behaviour currently unknown. |
| Property name | Type | Description |
|---|---|---|
| AnimationName | String | Behaviour currently unknown. |
| SoundName | String | Behaviour currently unknown. |
A dictionary of NpcActionContents assigned to specific NpcAction as a key.
Enum specifying NPC's action - None, Idle, Idle2, Idle3, Walk, Turn, Talk, Burrow, Hide, ComeOut, TakeOff, Fly or Land.