STF Format¶
STF is a file format for 3D assets, intended for interchange between 3D modeling-tools and game-engines.
Concept¶
STF files are made up of a binary header, a Json definition and a set of binary buffers.
The Json definition contains meta information, resources and buffer references.
Resources have a type property, and are identified by a unique ID as a string.
STF implementations provide resource-handlers, which convert between STF resources of a specific type and a specific application resource.
I.e. a resources-handler for stf.mesh in the Blender STF implementation would convert the STF-resource to and from Blenders bpy.types.Mesh.
A set of resources-handlers that any valid STF implementation has to provide is specified in Core Resources.
STF implementations must provide an easy to use plugin system for resources-handlers. If in any way possible, resources-handlers should be hot-loadable at runtime.
Format Properties¶
The file extension for stf files is
.stf.The media-type for stf binary files is
model/stf+binary.The STF binary header is stored in
little endianbyte order.The Json definition is encoded as
utf8.STF uses the same coordinate system as glTF 2.0. (See glTF-2.0. coordinate-system-and-units)
Binary Format¶
An STF binary file consists of a binary header, a json-definition, and zero or more binary buffers.
Length (Bytes) |
Content |
|---|---|
4 |
Magic number: |
4 |
STF binary format version major |
4 |
STF binary format version minor |
4 |
Number of buffers, including the Json definition buffer |
8 * {number of buffers} |
Buffer lengths in bytes |
{length of all buffers} |
Buffers |
The Json definition is the first and only required buffer.
Json Definition¶
The root Json element is an object. It contains 3 properties: stf, resources and buffers.
Json Types¶
The following special Json-types are specified:
Resource-ID¶
Buffer-ID¶
Resource-Path¶
A Json array which contains Resource-IDs and other path elements needed to target a specific resource. As some resources may be instantiated multiple times, this is needed to resolve one specific instance.
stf object¶
The stf object holds meta information.
Properties:
Key |
Required |
Type |
Description |
|---|---|---|---|
version |
Yes |
list |
List of two integers, specifying the major and minor version of the STF files Json definition. |
root |
Yes |
Resource-ID |
ID of the root resource |
asset_info |
No |
Asset-Info-Object |
Meta information such as authors, license or documentation link. |
asset_properties |
No |
Map<String, String> |
User defined properties |
generator |
No |
String |
The name of the STF implementation that created this file. |
timestamp |
No |
String |
ISO 8601 date and time in UTC. |
metric_multiplier |
No |
Float |
Which number represents one meter. The default value is |
Key |
Required |
Type |
Description |
|---|---|---|---|
asset_name |
No |
String |
|
version |
No |
String |
|
url |
No |
String |
|
author |
No |
String |
|
license |
No |
String |
|
license_url |
No |
String |
|
documentation_url |
No |
String |
The root resource must be a stf.prefab. It represents the assets scene-hierarchy.
stf object example
"stf": {
"version": [
0,
0
],
"root": "a6452f90-3edb-4fcd-bfe5-f7860a1ea665",
"asset_info": {
"asset_name": "Default Cube"
},
"asset_properties": {
"Foo": "Bar"
},
"generator": "stf_blender",
"generator_version": "0.1.0",
"timestamp": "2026-03-24T10:37:45.230480+00:00",
"metric_multiplier": 1
}
resources object¶
The resources object is a map of resource objects identified by an ID.
The various resource objects describe the files actual content. Each resource-type defines arbitrary additional properties.
Resource object base properties:
Key |
Required |
Type |
Description |
|---|---|---|---|
type |
Yes |
String |
Type of the resource. |
referenced_resources |
No |
List |
IDs of resources this resource references. |
referenced_buffers |
No |
List |
IDs of buffers this resource references. |
name |
No |
String |
Display name of the resource. |
version |
No |
Int |
Version of this resource. The default value is |
degraded |
No |
Boolean |
Has this resource lost information at some point, but retained the same ID. The default is |
Resources must store all references to other resources and buffers in the referenced_resources and referenced_buffers fields respectively.
If an STF implementation doesn’t support a resource, it will preserve and re-export it along with all its relationships.
Resource Categories¶
Resources are in one of the following categories: Data, Node, Instance and Component.
Each of these categories have additional properties.
The information about what category a resource is, must be known by the resource-type’s implementation and is not contained in STF files itself.
Data¶
Support for plugins of this category is required.
Data resource base properties:
Key |
Required |
Type |
Description |
|---|---|---|---|
fallback |
No |
Resource-ID |
ID of a resource that should be used in case this one’s type is not supported in this implementation |
components |
No |
List |
Component resource IDs |
Node¶
For now only stf.node and stf.bone exist.
Support for handler plugins of this category is not required.
Node resource base properties:
Key |
Required |
Type |
Description |
|---|---|---|---|
enabled |
No |
boolean |
True by default |
children |
No |
List |
IDs of child-nodes |
components |
No |
List |
Component resource IDs |
Instance¶
They represent an instance of a data resource in the scene hierarchy.
These include for example mesh or armature instances.
Instances can provide data relevant for the instance of the resource, such as an armatures pose or meshes blendshape value or material assignments.
An instance resource can be referenced only once by a Node resource.
Support for handler plugins of this category is required.
Instance resource properties:
Key |
Required |
Type |
Description |
|---|---|---|---|
enabled |
No |
boolean |
True by default |
Component¶
They Represents additional functionality or information for Data and Node resources.
A component resource can be referenced only once by a Data or Node resource.
Support for handler plugins of this category is required.
Component resource properties:
Key |
Required |
Type |
Description |
|---|---|---|---|
enabled |
No |
boolean |
True by default |
exclusion_group |
No |
string |
A group from which an importer will choose the best |
resources object example
"resources": {
"0060c2b8-d856-4459-a88a-16e659792e6f": {
"type": "stf.material",
"name": "Body",
"properties": {
"albedo.texture": {
"type": "image",
"values": [
{
"image": 0
}
]
},
"roughness.texture": {
"type": "image",
"values": [
{
"image": 1
}
]
}
},
"style_hints": [
"realistic",
"pbr"
],
"shader_targets": {
"blender": [
"ShaderNodeBsdfPrincipled"
]
},
"referenced_resources": [
"f518a35d-d788-4692-a2dd-84d036d259e8",
"edc8188f-7d85-419c-967f-5f7b427d8288"
]
},
{
// ...
}
}
buffers object¶
The buffers object is a map of buffer objects identified by an ID.
Each buffer object has a type property. Any further properties are defined in the buffer-type’s definition.
For now, stf.buffer.included is the only supported buffer type. Support for hot-loading different buffer-types is not required.
stf.buffer.included¶
This type represents a buffer contained in the same file.
stf.buffer.included properties:
Key |
Required |
Type |
Description |
|---|---|---|---|
index |
Yes |
Int |
Index of the binary buffer in the file. An index of 0 means the first buffer after the Json definition buffer. |
buffers object example
"buffers": {
"2c04d7f9-96cd-4867-baf3-2a54d4d31a67": {
"type": "stf.buffer.included",
"index": 666
},
{
// ...
}
}
Minimal Definition Example¶
Default Cube.stf
{
"stf": {
"version": [
0,
0
],
"root": "a6452f90-3edb-4fcd-bfe5-f7860a1ea665",
"asset_info": {
"asset_name": "Default Cube"
},
"asset_properties": {
"Foo": "Bar"
},
"generator": "stf_blender",
"generator_version": "0.1.0",
"timestamp": "2026-03-24T10:37:45.230480+00:00",
"metric_multiplier": 1
},
"resources": {
"ec16a927-1b26-4157-a3f2-71455d05e2bf": {
"type": "stf.material",
"name": "Material",
"properties": {
"albedo.color": {
"type": "color",
"values": [
[
0.800000011920929,
0.800000011920929,
0.800000011920929,
1.0
]
]
},
"roughness.value": {
"type": "float",
"values": [
0.5
]
},
"metallic.value": {
"type": "float",
"values": [
0.0
]
}
},
"style_hints": [
"realistic",
"pbr"
],
"shader_targets": {
"blender": [
"ShaderNodeBsdfPrincipled"
]
}
},
"ededda7a-651c-44a9-b5a2-b6b6ff799881": {
"type": "stf.mesh",
"name": "Cube",
"referenced_resources": [
"ec16a927-1b26-4157-a3f2-71455d05e2bf"
],
"material_slots": [
0
],
"float_width": 4,
"indices_width": 1,
"referenced_buffers": [
"a2678730-f63c-4415-85a8-9426bfc7242e",
"be7acc51-f47c-406c-82f6-c7ea7833ed4d",
"c29e0d3a-9b4d-444b-93f1-e3163332fdcb",
"d3329a1a-b79a-4d27-b16d-f7af2420951a",
"97925952-70a7-4773-96fe-00e44d4cdfee",
"05039913-1397-4f3c-9b54-d514ace748e7",
"4d86408e-84f5-4f05-86b2-82f3a8803f9d",
"6cdbf5c5-e770-4bbf-924f-4c10818826e9",
"e7b0b03d-c004-4876-97a3-c4a26b7ac3c9",
"ecb6ef8b-618c-4dcd-a0b0-0a0cf70cf143",
"42a32c5f-edb6-43c3-a028-fa2a75b46671"
],
"vertices": 0,
"face_corners": 1,
"splits": 2,
"split_normals": 3,
"uvs": [
{
"name": "UVMap",
"uv": 4
}
],
"tris": 5,
"material_indices_width": 1,
"faces": 6,
"material_indices": 7,
"sharp_face_indices": 8,
"lines": 9,
"sharp_edges": 10,
"components": [
"5b09c146-b626-4fb4-a4fa-b33b0e5085e2"
]
},
"5b09c146-b626-4fb4-a4fa-b33b0e5085e2": {
"type": "stfexp.mesh.seams",
"indices_width": 1,
"referenced_buffers": [
"a5f59428-b776-4e4e-a203-1bf60b0912db"
],
"seams": 0
},
"bc0a2119-7e10-4a01-a169-a1219c0dce90": {
"type": "stf.instance.mesh",
"name": "",
"referenced_resources": [
"ededda7a-651c-44a9-b5a2-b6b6ff799881"
],
"mesh": 0,
"materials": [
null
]
},
"00058dcb-4e27-4067-9163-3f9ef959faf1": {
"type": "stf.node",
"name": "Cube",
"children": [],
"trs": [
[
0,
0,
0
],
[
0,
0,
0,
1
],
[
1,
1,
1
]
],
"referenced_resources": [
"bc0a2119-7e10-4a01-a169-a1219c0dce90"
],
"instance": 0,
"components": [
"a5663bce-e160-48c4-8da1-b79271d2d7dc"
]
},
"a5663bce-e160-48c4-8da1-b79271d2d7dc": {
"type": "org.blender.object.rotation_mode",
"rotation_mode": "QUATERNION"
},
"9d2ebb30-0e26-4f57-96bb-c91198140849": {
"type": "stfexp.light",
"name": "",
"light_type": "point",
"range": 0.10000000149011612,
"brightness": 1000.0,
"color": [
1.0,
1.0,
1.0
],
"shadow": true
},
"b12620eb-5c3a-433c-a93c-4c5d6d158f2b": {
"type": "stf.node",
"name": "Light",
"children": [],
"trs": [
[
4.076245307922363,
5.903861999511719,
-1.0054539442062378
],
[
0.16907574236392975,
0.7558803558349609,
-0.27217137813568115,
0.570947527885437
],
[
1,
1,
1
]
],
"referenced_resources": [
"9d2ebb30-0e26-4f57-96bb-c91198140849"
],
"instance": 0,
"components": [
"2a8ff6fb-a04f-424f-ad30-1842dbe34e9e"
]
},
"2a8ff6fb-a04f-424f-ad30-1842dbe34e9e": {
"type": "org.blender.object.rotation_mode",
"rotation_mode": "XYZ"
},
"e779506a-d4c2-400d-86d0-652d938560d4": {
"type": "stfexp.camera",
"name": "",
"projection": "perspective",
"aspect_ratio": 1.7777777777777777,
"fov": 0.39959652046304894
},
"1fe7444e-7090-495b-90e7-ca3cbc167930": {
"type": "stf.node",
"name": "Camera",
"children": [],
"trs": [
[
7.358891487121582,
4.958309173583984,
6.925790786743164
],
[
0.483536034822464,
0.33687159419059753,
-0.20870360732078552,
0.7804827094078064
],
[
1,
1,
1
]
],
"referenced_resources": [
"e779506a-d4c2-400d-86d0-652d938560d4"
],
"instance": 0,
"components": [
"f9a4f1c4-e95e-419c-b714-64483f208ded"
]
},
"f9a4f1c4-e95e-419c-b714-64483f208ded": {
"type": "org.blender.object.rotation_mode",
"rotation_mode": "XYZ"
},
"a6452f90-3edb-4fcd-bfe5-f7860a1ea665": {
"type": "stf.prefab",
"name": "Collection",
"root_nodes": [
0,
1,
2
],
"animations": [],
"referenced_resources": [
"00058dcb-4e27-4067-9163-3f9ef959faf1",
"b12620eb-5c3a-433c-a93c-4c5d6d158f2b",
"1fe7444e-7090-495b-90e7-ca3cbc167930"
]
}
},
"buffers": {
"a2678730-f63c-4415-85a8-9426bfc7242e": {
"type": "stf.buffer.included",
"index": 0
},
"be7acc51-f47c-406c-82f6-c7ea7833ed4d": {
"type": "stf.buffer.included",
"index": 1
},
"c29e0d3a-9b4d-444b-93f1-e3163332fdcb": {
"type": "stf.buffer.included",
"index": 2
},
"d3329a1a-b79a-4d27-b16d-f7af2420951a": {
"type": "stf.buffer.included",
"index": 3
},
"97925952-70a7-4773-96fe-00e44d4cdfee": {
"type": "stf.buffer.included",
"index": 4
},
"05039913-1397-4f3c-9b54-d514ace748e7": {
"type": "stf.buffer.included",
"index": 5
},
"4d86408e-84f5-4f05-86b2-82f3a8803f9d": {
"type": "stf.buffer.included",
"index": 6
},
"6cdbf5c5-e770-4bbf-924f-4c10818826e9": {
"type": "stf.buffer.included",
"index": 7
},
"e7b0b03d-c004-4876-97a3-c4a26b7ac3c9": {
"type": "stf.buffer.included",
"index": 8
},
"ecb6ef8b-618c-4dcd-a0b0-0a0cf70cf143": {
"type": "stf.buffer.included",
"index": 9
},
"42a32c5f-edb6-43c3-a028-fa2a75b46671": {
"type": "stf.buffer.included",
"index": 10
},
"a5f59428-b776-4e4e-a203-1bf60b0912db": {
"type": "stf.buffer.included",
"index": 11
}
}
}