FOX5 File Format Specification

This is the specification for the new Furcadia graphics format introduced in Version 31 (The Second Dreaming).


FOX5 Container Format

A given FOX file contains three main elements, described in further detail below:

  • Command Block: Metadata about the objects and shapes within the files: properties, numbers, KitterSpeak steps, etc. Compressed.
    • Location: Always at the very beginning of the file.
    • Size: Variable, defined by the Magic Footer.
      When decompressed, contains the data described in the ‘Command Block’ section of this document.
  • Images: 8-bit or 32-bit images whose locations/sizes are defined by the ‘image list’ command within the Command Block. Each image is individually compressed for fast random-access loading.
    • Location: Immediately following the Command Block. Each image is stored consecutively - i.e. image 1 is directly followed by image 2, and so on.
    • Size: Variable, equal to the sum of all compressed sizes set in the image list.
      • Image pixels are always stored top-down, left-to-right: i.e. (0,0), (1,0), (2,0), (3,0), … (0,1), (1,1), (2,1), (3,1) … (width-1, height-1)
      • 8-bit images use Furcadia palette indices.
      • 32-bit images use an A R G B byte order.
      • Implementations may skip image formats they don’t understand (if such a case ever occurs) by simply skipping past the compressed block.
  • Magic Footer: Identifies the version of the FOX format in use, and contains some basic info about how to decode the file correctly.
    • Location: Always at the very end of the file.
    • Size: Version-dependent. Currently 0x14 (20) bytes.
    • 0x00: UInt8: Compression Type
    • 1 = ZLib (reserved, currently unused), 2 = LZMA
    • 0x01: UInt8: Encryption Type
    • 0 = No Encryption; all other values are reserved
    • 0x02: UInt8: Reserved
    • 0x03: UInt8: Reserved
    • 0x04: UInt32: Compressed Size of Data Block (e.g. 0x3EA)
    • 0x08: UInt32: Uncompressed Size of Data Block (e.g. 0x3683)
    • 0x0C: Magic String: ‘FOX5.1.1’ (this may change if the format is updated in future Furcadia releases)
      • The magic string will always be at the end of the file, so implementations can use it to determine which format is in use and therefore where the footer begins.

All fields are big-endian - i.e. the 32-bit value 0x12345678 is encoded as 12 34 56 78, and 1 as 00 00 00 01.

Compression

LZMA (Compression Type 2 in the FOX5 footer) is used as the standard algorithm for all FOX5 files and supported by all implementations. Do not confuse this with LZMA2, which is similar but different!

Reference source code is available here: http://7-zip.org/sdk.html

Notes about LZMA compression settings
The ‘Fast bytes’ setting appears to have the largest impact on the time it takes to compress Furcadia art: the minimum of 5 results in very fast compression with mediocre ratios, while values of around 32 and higher result in rather slow compression with very good ratios.

Dictionary sizes can be kept low (Furcadia currently uses a dictionary size equal to the uncompressed data size or to 1MB, whichever is smaller). This reduces compression time and memory usage.

The Furcadia client does not re-compress individual sprites on dream upload, so implementations are encouraged to prefer slower settings which achieve a higher ratio in order to minimise dream upload/download sizes.

back to top

Command Block

The first compressed block in the FOX5 format contains the command block, which encodes all the metadata relating to objects, shapes, etc. inside the FOX5 file.

The command block begins with four null bytes (reserved for future use) and is then followed by a sequence of commands (each one represented as one UInt8 command ID followed by command-specific arguments).

For example, the following command block for a FOX File maps to the following sequence of commands:

Example Block
00 00 00 00
4C 00 00 00 00 01
53 00 00 00 01 00 00 00 1A 00 08 00 08 01
4C 01 00 00 00 02
[...]
3C
[...]
3C
3C

Command Sequence
Reserved bytes
‘L’ Start List: Level = File, numberOfItems = 1
‘S’ ImageList: NumImages = 1: {compressedSize=0x1A, width=8, height=8, format=1}
‘L’ Start List: Level = Object, numberOfItems = 2
(Data for first object)
‘<’ End List Item
(Data for second object)
‘<’ End List Item
‘<’ End List Item

Expected Structure

The command block should be structured as follows:

  • List: File (Count must always be 1)
    • ImageList
    • Generator
    • List: Object
      • ObjectId
      • Name
      • Description
      • Authors
      • Revisions
      • Keywords
      • License
      • Portal
      • EditType
      • ObjectFlags
      • ObjectMoreFlags
      • FxFilter
      • List: Shape
        • ShapePurpose
        • Direction
        • ShapeState
        • Ratio
        • KitterSpeak
        • List: Frame
          • FrameOffset
          • FurreOffset
          • List: Sprite
            • SpritePurpose
            • SpriteOffset

Commands within a given nesting level may be provided in any order, with one exception: ImageList must be provided before the Object list.

If a non-List command occurs multiple times within a given block (i.e. two ObjectFlags commands for one object, or two KitterSpeak commands for one shape), then the last one will take precedence.

If multiple List commands occur within a given block (i.e. two Shape lists in the same Object), then their contents will be effectively combined.

If a command is provided at the wrong nesting level (i.e. FrameOffset directly inside an Object, or Ratio directly inside a Sprite), then it should be ignored.

If a command is not provided, then a default value will be used (see the table below for what is used in which command).

Command IDs and Arguments

Value Level Meaning Arguments/Description Default
0x00 -'\0' Any NO-OP padding byte None n/a
0x4C - 'L' Any Start List UInt8 Level, UInt32 numberOfItems
This is always the first command in the command block.
Level defines the nesting level, which should be sequential with no gaps, and have the following defined values:
0=File; 1=Object; 2=Shape; 3=Frame; 4=Channel.
The following values are reserved but unlikely to ever be used: 5=KS-Line; 6=Sprite; 7=Overlay
0, 0 = Unspecified type, No items
0x3C - '<' Any
End List Item
None n/a
0x67 - 'g' File Generator UInt8 Generator ID
0 = unspecified
1-127 reserved for Furcadia use
128-255 reserved for third-party applications
0 = Unspecified
0x53 - 'S' File ImageList UInt32 NumImages
(UInt32 compressedSize, UInt16 width, UInt16 height, UInt8 format)
List begins at Image 1. Zero-size Image 0 always exists as an ‘empty image’, and isn't specified.
Width and height should not be larger than 2048 each.
Format:
0 = 8-bit (∴ uncompressedSize = width * height)
1 = 32-bit (∴ uncompressedSize = width * height * 4)
No images exist except for the implicit empty ‘image 0’.
0x72 - ‘r’ Object Revision Count UInt16 Amount
Incremented once every time a new author is added.
0
0x61 - 'a' Object Author History UInt16 NumStrings
(UInt16 StringLengthInBytes
(UInt8 UTF-8 StringData, ...), ...)
0 = Empty list
0x6C - 'l' Object License (WIP) UInt8 License
0 = FC Standard (FC-BY-SA)
1 = FC Freedom (FC0)
2 = FC Limited (FC-BY-NC-SA)
3 = FC Exclusive (FC-ND-NC-SA)
4 = FC Private (FC-Private-SA)
5 = FC Conditional (FC-BY-X-SA)
Other values are reserved.
0 = FC-BY-SA
0x6B - 'k' Object Keywords UInt16 NumStrings
(UInt16 StringLengthInBytes
(UInt8 UTF-8 StringData, ...), ...)
0 = Empty list
0x6E - 'n' Object Name UInt16 StringLengthInBytes
(UInt8 UTF-8 StringData, ...)
"" = Empty string
0x64 - ‘d’ Object Description UInt16 StringLengthInBytes
(UInt8 UTF-8 StringData, …)
“” = Empty string
0x21 - '!' Object Flags UInt8 Flags (bitfield, same order as fox)
0x01 = Walkable (Walls, Floors, Items only)
0x02 = Gettable (Items only)
0x04 = Sittable (Items only)
0x08 = Flyable (Floors only)
0x10 = Swimmable (Floors only)
0x20 = Clickable, blocks clickthru (Buttons, avatars)
0x40 = MouseOver hilite, blocks clickthru (Avatars)
0x80 = Kickable (evades player, eg Red ball item)

0 = None true.

0x50 - 'P' Object Teleport dreamurl UInt16 StringLengthInBytes
(UInt8 ISO8859-1 StringData, ...)
Teleport object URI string. Implementations:
Must save and handle goback portals with the url ["command://goback"].
Must include the [furc://] protocol when saving all other portals;
Should handle URIs with no protocol by prefixing them with [furc://],
Must ignore all other protocols, ESPECIALLY the [command:\\] protocol, apart from that one whitelisted value.
"" - Item is not a static portal. (this command only makes sense on Items).
0x3F - '?' Object MoreFlags UInt32 Extended flags (bitfield)
[Dream Pad types - see Purpose]
0x0000 0000 - Everyone can upload to this pad, as restricted by DS or share commands. (default value)
0x0000 0001 - SS
0x0000 0002 - GS
0x0000 0080 - Lower Group Packages
0x0000 0100 - High Group Packages
0x0000 8000 - Dep Staff/Associates
[Avatar types]
0x0000 0001 - Hopping
0x0000 0002 - Flying
0x0000 0004 - Swimming
0x0000 0008 - Child
0 = None true.
0x69 - 'i' Object Object Identifier Int32 ObjectNumber
-1: Object number is determined by its position in the file.
All other values: This object should have the number provided. (This behaves like the “FS2 replacement number” option in legacy FS2/FOX files.)
-1 if previous object had ID -1. Otherwise, previous object’s ID + 1.
0x74 - 't' Object Edit Type UInt8 type
See ‘Object/Shape Structure’ section for more details.
0 = Unspecified
0x46 - 'F' Object FX Filter Type UInt8 TargetLayer, UInt8 BlendMode
TargetLayer is:
0x00 = 'vb' layer: that is, blit directly to the screen.
0x01 = 'sfx' layer: that is, a separate layer composited to the isometric area after all other rendering complete.
BlendMode is:
0x00 - none
0x01 - addition
0x04 - darken
0x05 - difference
0x07 - hard light
0x08 - lighten
0x09 - multiply
0x0A - normal
0x0B - overlay
0x0C - screen
0x0E - subtract
0x0F - alpha
0x10 - erase
(0,0) - vb layer, no filter.
0x70 - 'p' Shape Purpose UInt8 Purpose
Identifies a Shape in tandem with State, Direction and Ratio (see the Object/Shape Structure section).
0 = Unspecified/default
[0*: UI element range]
01 = Menu Icon
02 = UI Button
03 = Butler
04 = Portrait
05 = DS Button
[1*: Avatar element range]
11 = Avatar
[2*: Layer range]
21 = Floor
22 = Item
23 = Wall
24 = Region
25 = Effect
28 = Pad Item (See Portal Items section below)
29 = Portal Item
[3*: Textarea item range]
35 = Specitag
[4*: ‘Filters’ range]
41 = Lighting
42 = Ambience
0 = Unspecified
0x73 - 's' Shape State
Depends on Purpose.
Avatars: Gender.
Button: Clickstate
UInt8 StateBitfield
Identifies a Shape in tandem with Purpose, Direction and Ratio (see the Object/Shape Structure section).
0x00 - Any/default/none specified
[Furres, Ports, Specitags: bitfield]
0x01 - Female
0x02 - Male
0x04 - Unspecified
[Furres]
0x10 - Standing (Stand 0; R ft fwds)
0x20 - Lie
0x30 - Standing (Stand 1, feet together)
0x40 - Sit
0x50 - Standing (Stand 2, L ft fwds)
[Buttons, bitfield]
0x01 - Clicked
0x02 - Mouseover
0x04 - Activated/Toggled on
[Portals - show highest matching shape for uploader. Note similarity to MoreFlags vals for pads]
0x00 - Normal portal
0x01 - SS portal
0x02 - GS portal
0x03 to 0x07 - Reserved
0x08 - Lower Group Packages
0x09 - High Group Packages (UNUSED)
0x0a to 0x0f - Reserved
0x10 - Dep Staff/Associate portal
0x11 - Server only portal
0x00 - no specified gender/state. Overridden by any Object with gender set.
0x44 - 'D' Shape Direction UInt8 Direction
Identifies a Shape in tandem with Purpose, State and Ratio (see the Object/Shape Structure section).
0 - Unspecified
1 - SW
2 - S
3 - SE
4 - W
5 - No direction
6 - E
7 - NW (+ Left Wall)
8 - N
9 - NE (+ Right Wall)
10 - Up
11 - Down
0 - Unspecified
0x52 - 'R' Shape Ratio for Scale UInt8 Numerator, UInt8 Denominator
Identifies a Shape in tandem with Purpose, State and Direction (see the Object/Shape Structure section).
Denominator may be zero in cases where fractional scaling does not make sense (e.g. icons).
0/0 - used for shape types that can never have scaled versions.
0x4B - 'K' Shape KS Script UInt16 NumSteps
(UInt16 StepId, Int16 StepArg1, Int16 StepArg2), ...
No KS for this Shape.
0x6F - 'o' Frame Frame Offset Int16 OffsetX, Int16 OffsetY (0,0) - no offset.
0x66 - 'f' Frame Furre Offset Int16 OffsetX, Int16 OffsetY (0,0) - no offset.
0x43 - 'C' Sprite Purpose UInt16 SpritePurpose
Sets how a particular Sprite is used (see the Frame/Sprite Structure section).
0x20 = Sprite contains remapping data.
0x40 = Sprite is the shadow layer.
0x80 = Sprite is the markup layer. (shown in FOX Editor, ignored elsewhere, potentially stripped for dream uploads)

Same as previous, or if no previous, then:
0x00 - no remap, not shadow or markup.

0x63 - 'c' Sprite Image ID UInt16 ImageID
References an Image described within the ImageList command.
Previous Image id + 1, or 0.
0x4F - 'O' Sprite Offset UInt16 OffsetX, UInt16 OffsetY
The number of blank/empty rows and columns of pixels that have been cropped off the left and top of this sprite for more efficient storage.
(0,0) = no omitted pixels.
back to top

Object/Shape Structure

From a user-facing perspective, the FOX5 format allows users to create complex objects like “Floor”, “Avatar” and “Wall” which contain multiple different shapes with distinct imagery, positioning and KitterSpeak.

This is implemented in FOX5 by storing a set of nested structures (as defined in the ‘Expected Structure’ section of the ‘Command Block’ section) and through a series of important properties:

  • Object / Edit Type: Defines what type a particular object purports to be
  • Shape / Purpose, State, Direction, Ratio: Defines what part of that object is represented by a particular shape

It is expected that a particular object should only contain specific shapes (as enforced by the FOX Editor user interface). Behaviour is undefined if these rules are ignored -- so for instance, while it is technically possible to add a Portrait shape to an Item object, or a 3:1 scale Floor shape to a Wall object, implementations may ignore these or not render them correctly.

If a particular Shape is not included, implementations may decide how to obtain a suitable shape from others which do exist. For example, if a Gendered Avatar contains unspecified and male shapes but not female shapes, then the unspecified shapes will be used for female characters that use that avatar. Likewise, if an Item contains a 2:1 representation and needs to be rendered at 1:1, then a client may downscale the 2:1 shape to 50% of its original size.

The following tables explain what shapes may be included in an object that has a given Edit Type, and what properties they should have.

Default/Unspecified (0), System (14)

Name

Purpose

State

Direction

Scale

Default Shape

0: Default

0

0

0:0

Floor (1), Item (2), Effect (3), Region (7), Lighting (10), Ambience (11)

Name

Purpose

State

Direction

Scale

Tiny Icon

1: Menu Icon

0

0

1:0

Small Icon

1: Menu Icon

0

0

2:0

Large Icon

1: Menu Icon

0

0

3:0

Showcase Icon

1: Menu Icon

0

0

4:0

Small

(depends on object type)

0

0

1:1

Large

(depends on object type)

0

0

2:1

Wall (8)

Name

Purpose

State

Direction

Scale

Tiny Icon

1: Menu Icon

0

0

1:0

Small Icon

1: Menu Icon

0

0

2:0

Large Icon

1: Menu Icon

0

0

3:0

Showcase Icon

1: Menu Icon

0

0

4:0

Small Right Wall

23: Wall

0

7

1:1

Small Left Wall

23: Wall

0

9

1:1

Large Right Wall

23: Wall

0

7

2:1

Large Left Wall

23: Wall

0

9

2:1

Portal (15)

Name

Purpose

State

Direction

Scale

Tiny Icon

1: Menu Icon

0

0

1:0

Small Icon

1: Menu Icon

0

0

2:0

Large Icon

1: Menu Icon

0

0

3:0

Showcase Icon

1: Menu Icon

0

0

4:0

Small Upload Pad

28: Pad

0

0

1:1

Small Standard Portal

29: Portal

0

0

1:1

Small Silver Sponsor Portal

29: Portal

1

0

1:1

Small Gold Sponsor Portal

29: Portal

2

0

1:1

Small Group Package Portal

29: Portal

8

0

1:1

Small High Group Package Portal

29: Portal

9

0

1:1

Small Staff Portal

29: Portal

0x10

0

1:1

Small Special Portal

29: Portal

0x11

0

1:1

Large Upload Pad

28: Pad

0

0

2:1

Large Standard Portal

29: Portal

0

0

2:1

Large Silver Sponsor Portal

29: Portal

1

0

2:1

Large Gold Sponsor Portal

29: Portal

2

0

2:1

Large Group Package Portal

29: Portal

8

0

2:1

Large High Group Package Portal

29: Portal

9

0

2:1

Large Staff Portal

29: Portal

0x10

0

2:1

Large Special Portal

29: Portal

0x11

0

2:1

Portrait Set (4)

Name

Purpose

State

Direction

Scale

Male Portrait

4: Portrait

2

0

0:0

Female Portrait

4: Portrait

1

0

0:0

Unspecified Portrait

4: Portrait

4

0

0:0

Male Specitag

35: Specitag

2

0

0:0

Female Specitag

35: Specitag

1

0

0:0

Unspecified Specitag

35: Specitag

4

0

0:0

Avatar (5), Gendered Avatar (6)

Name

Purpose

State

Direction

Scale

Tiny Icon

1: Menu Icon

0

0

1:0

Small Icon

1: Menu Icon

0

0

2:0

Large Icon

1: Menu Icon

0

0

3:0

Showcase Icon

1: Menu Icon

0

0

4:0

Male Portrait

4: Portrait

2

0

0:0

Female Portrait

4: Portrait

1

0

0:0

Unspecified Portrait

4: Portrait

4

0

0:0

Male Specitag

35: Specitag

2

0

0:0

Female Specitag

35: Specitag

1

0

0:0

Unspecified Specitag

35: Specitag

4

0

0:0

SW Sitting

11: Avatar

0x40 | (gender-specific)

1

(varies)

SW Walk 1

11: Avatar

0x10 | (gender-specific)

1

(varies)

SW Standing

11: Avatar

0x30 | (gender-specific)

1

(varies)

SW Walk 2

11: Avatar

0x50 | (gender-specific)

1

(varies)

SE Sitting

11: Avatar

0x40 | (gender-specific)

3

(varies)

SE Walk 1

11: Avatar

0x10 | (gender-specific)

3

(varies)

SE Standing

11: Avatar

0x30 | (gender-specific)

3

(varies)

SE Walk 2

11: Avatar

0x50 | (gender-specific)

3

(varies)

NW Sitting

11: Avatar

0x40 | (gender-specific)

7

(varies)

NW Walk 1

11: Avatar

0x10 | (gender-specific)

7

(varies)

NW Standing

11: Avatar

0x30 | (gender-specific)

7

(varies)

NW Walk 2

11: Avatar

0x50 | (gender-specific)

7

(varies)

NE Sitting

11: Avatar

0x40 | (gender-specific)

9

(varies)

NE Walk 1

11: Avatar

0x10 | (gender-specific)

9

(varies)

NE Standing

11: Avatar

0x30 | (gender-specific)

9

(varies)

NE Walk 2

11: Avatar

0x50 | (gender-specific)

9

(varies)

SW Laying

11: Avatar

0x20 | (gender-specific)

1

(varies)

SE Laying

11: Avatar

0x20 | (gender-specific)

3

(varies)

NW Laying

11: Avatar

0x20 | (gender-specific)

7

(varies)

NE Laying

11: Avatar

0x20 | (gender-specific)

9

(varies)

Small Butler

3: Butler

(varies)

0

1:0

Large Butler

3: Butler

(varies)

0

2:0

For brevity, the many Avatar permutations have not been listed in the table, however:

Type 5 (Avatar) includes a Small and Large copy of each Avatar shape in the table above, with scale 1:1 and 2:1 respectively.
Type 6 (Gendered Avatar) includes six copies of each Avatar shape in the table above: Male Small, Male Large, Female Small, Female Large, Unspec Small and Unspec Large. The Male shapes have their State bitwise OR-ed with 2, the Female shapes with 1 and the Unspecified shapes with 4. As with non-gendered avatars, the Small and Large have scale 1:1 and 2:1 respectively.

Furthermore, Type 6 (Gendered Avatar) replaces the two non-gender-specific butler shapes with six gender-specific butler shapes. As with the avatar shapes, the State is set to 2 for Male, 1 for Female and 4 for Unspecified.

Button (12)

Name

Purpose

State

Direction

Scale

Normal

2: UI Button

0

0

0:0

Mouse Over

2: UI Button

2

0

0:0

Clicked

2: UI Button

1

0

0:0

Toggled

2: UI Button

4

0

0:0

DS Button (13)

Name

Purpose

State

Direction

Scale

Normal

5: DS Button

0

0

0:0

Mouse Over

5: DS Button

2

0

0:0

Clicked

5: DS Button

1

0

0:0

Toggled

5: DS Button

4

0

0:0

back to top

Frame/Sprite Structure

The FOX5 format allows a frame to contain multiple sprites. The behaviour and use of a particular sprite is defined by the value provided to its SpritePurpose command.
The following kinds of sprites are currently permitted:

  • Image Layer
    • Should always be the first sprite in a frame; behaviour is undefined otherwise
    • Purpose may be 0 (for a standard image) or 0x20 (for a remapping image -- described in the following section)
  • Shadow Layer
    • Optional
    • Purpose must be 0x40
    • This sprite is rendered by clients at 50% opacity to a separate layer
    • This sprite is only used by certain object/shape types (avatars, items, etc)
  • Markup Layer
    • Optional
    • Purpose must be 0x80
    • This sprite is never used by clients, and exists simply as an aid to artists which is displayed and can be edited by FOX Editor

Behaviour is undefined if SpritePurpose values other than 0, 0x20, 0x40 or 0x80 are used, or if two sprites for the same layer exist within one frame.

back to top

Remapping

8-bit Remapping

FOX5 supports 8-bit images purely to ease backwards compatibility with legacy Furcadia art. Their use is highly discouraged.

32-bit Remapping

Images that take advantage of 32-bit remapping are just normal images with one distinction: any pixel with a blue value of 0 is remapped, while all other pixels do not change.

For remapped pixels, the red value specifies how dark that pixel is (0 = darkest, 255 = lightest) and the green value specifies how it remaps, as follows:

1

Badge

12

Trousers

2

Cape

13

Hair

3

Eye

14

Boots

4

Markings

15

Fur

6

Vest

16-23

Fur -> Markings blend

7

Accent

24-31

Fur -> Hair blend

9

Bracers

32-47

Markings -> Hair blend

10

Wing

255

Outline (for avatars)

back to top

Account E-Mail

Password