Task 679: .SPT File Format
Task 679: .SPT File Format
.SPT File Format Specifications
The .SPT file format is used by SpeedTree for tree models, particularly in games like Neverwinter Nights 2. It is a binary format with embedded strings for Bezier splines, used to define tree structure, wind animation, dimensions, and textures. The format is reverse-engineered and consists of a header, a main body with iterations of data (each iteration representing a level of tree branching or detail), and a footer. Data types include 4-byte integers, 4-byte floats, 1-byte booleans, and variable-length strings. Invariant bytes are fixed markers. The structure is as follows (based on the NWN2 variant):
Header (fixed size with variable string):
- File ID and version: 28-byte invariant binary (e.g.,
e8 03 00 00 0c 00 00 00 5f 5f 49 64 76 53 70 74 5f 30 32 5f ea 03 00 00 d0 07 00 00). - Main texture name: 4-byte integer (length) followed by ASCII string (ends in .tga, even if DDS is used).
- Invariant marker: 4-byte
d1 07 00 00. - Unused field: 4-byte unknown.
- Invariant marker: 4-byte
d2 07 00 00. - Unused field: 1-byte unknown.
- Invariant marker: 4-byte
d3 07 00 00. - Unused field: 4-byte unknown.
- Invariant marker: 4-byte
d5 07 00 00. - Unused field: 4-byte unknown.
- Invariant marker: 4-byte
d6 07 00 00. - Unused field: 4-byte unknown.
- Invariant marker: 4-byte
d7 07 00 00. - Unused field: 4-byte unknown.
- Invariant marker: 4-byte
f6 03 00 00. - Number of iterations: 4-byte integer (determines how many sets of splines and data follow).
Main Body (repeats for each iteration):
- Iteration start marker: 4-byte
f8 03 00 00. - Invariant marker: 4-byte
70 17 00 00. - Distortion spline: Variable-length formatted string (BezierSpline format; see below).
- Invariant marker: 4-byte
71 17 00 00. - Weight spline: Variable-length formatted string.
- Invariant marker: 4-byte
72 17 00 00. - Rough wind response spline: Variable-length formatted string.
- Invariant marker: 4-byte
73 17 00 00. - Fine wind response spline: Variable-length formatted string.
- Invariant marker: 4-byte
74 17 00 00. - Height/length spline: Variable-length formatted string.
- Invariant marker: 4-byte
75 17 00 00. - Rough radius spline: Variable-length formatted string.
- Invariant marker: 4-byte
76 17 00 00. - Fine radius spline: Variable-length formatted string.
- Invariant marker: 4-byte
77 17 00 00. - Angle spline: Variable-length formatted string.
- Invariant marker: 4-byte
78 17 00 00. - Mesh radial division: 4-byte integer.
- Invariant marker: 4-byte
79 17 00 00. - Mesh height division: 4-byte integer.
- Invariant marker: 4-byte
7a 17 00 00. - Start next iteration generation: 4-byte float.
- Invariant marker: 4-byte
7b 17 00 00. - End next iteration generation: 4-byte float.
- Invariant marker: 4-byte
7c 17 00 00. - Density of next iteration generation: 4-byte float.
- Invariant marker: 4-byte
7d 17 00 00. - Horizontal texture tiling: 4-byte float.
- Invariant marker: 4-byte
7e 17 00 00. - Vertical texture tiling: 4-byte float.
- Invariant marker: 4-byte
7f 17 00 00. - Horizontal texture alignment: 1-byte boolean (0 or 1).
- Invariant marker: 4-byte
80 17 00 00. - Vertical texture alignment: 1-byte boolean (0 or 1).
- Invariant marker: 4-byte
81 17 00 00. - Unknown ninth spline (possibly angle distortion): Variable-length formatted string.
- Iteration end marker: 4-byte
f9 03 00 00.
BezierSpline Format (for each spline property):
- Size: 4-byte integer (length of the entire string).
- String: "BezierSpline\tA\tB\tC {\tN\t[Point 0]\t...\t[Point N-1]\t}" where:
- A: 4-byte float (lowest value range).
- B: 4-byte float (highest value range).
- C: 4-byte float (random distortion).
- N: Integer (number of points, minimum 2).
- Each point: 5 floats "X Y WX WY W" (X/Y position, WX/WY normalized control direction, W weight).
- Note: Tabs (\t) separate values; splines define curves for properties like radius or wind.
Footer: Contains texture atlas data and other controls (not fully documented in available specs, but includes binary data for rendering parameters).
List of all properties intrinsic to this file format:
- File ID and version.
- Main texture name.
- Number of iterations.
- Per iteration: Distortion spline, weight spline, rough wind response spline, fine wind response spline, height/length spline, rough radius spline, fine radius spline, angle spline, unknown ninth spline.
- Per iteration: Mesh radial division, mesh height division.
- Per iteration: Start next iteration generation, end next iteration generation, density of next iteration generation.
- Per iteration: Horizontal texture tiling, vertical texture tiling, horizontal texture alignment, vertical texture alignment.
Two direct download links for .SPT files:
- https://metin2.download/file/JTKv7C2d3x1x33M3G8UB6ySN9XyK9Z4L/ (archive containing multiple .SPT SpeedTree models from Metin2 library).
- https://metin2.download/file/5HqZF6YjNUHOFobF0uHIPqIjXu29aNoe/ (archive containing SpeedTree modeler and library with .SPT examples).
Ghost blog embedded HTML JavaScript for drag-and-drop .SPT file dump:
Drag and drop .SPT file here
(Note: This is a basic implementation; full parsing would require handling all offsets and splines precisely.)
- Python class for .SPT:
import struct
import sys
class SPTFile:
def __init__(self, filename=None):
self.filename = filename
self.header = {}
self.iterations = []
if filename:
self.read()
def read(self):
with open(self.filename, 'rb') as f:
data = f.read()
offset = 0
# Header
self.header['id_version'] = data[offset:offset+28]
offset += 28
str_len = struct.unpack('<i', data[offset:offset+4])[0]
offset += 4
self.header['texture_name'] = data[offset:offset+str_len].decode('ascii')
offset += str_len
# Skip invariants and unknowns (adjust as per spec)
offset += 4 + 4 + 4 + 1 + 4 + 4 + 4 + 4 + 4 + 4 + 4 + 4
offset += 4 # f6
self.header['num_iterations'] = struct.unpack('<i', data[offset:offset+4])[0]
offset += 4
for i in range(self.header['num_iterations']):
iter_data = {}
offset += 4 # f8
offset += 4 # 70
iter_data['distortion_spline'], offset = self._parse_spline(data, offset)
# Repeat for other splines...
# Example for one:
# iter_data['weight_spline'], offset = self._parse_spline(data, offset)
# ... add for all 8 + ninth
iter_data['mesh_radial_div'] = struct.unpack('<i', data[offset:offset+4])[0]
offset += 4 # Adjust offsets in full impl
# Add other fields similarly: height div, floats, booleans
self.iterations.append(iter_data)
offset += 4 # f9
def _parse_spline(self, data, offset):
size = struct.unpack('<i', data[offset:offset+4])[0]
offset += 4
spline_str = data[offset:offset+size].decode('ascii')
offset += size
# Parse string to extract A, B, C, N, points if needed
return spline_str, offset
def write(self, filename=None):
if not filename:
filename = self.filename or 'output.spt'
with open(filename, 'wb') as f:
f.write(self.header['id_version'])
str_bytes = self.header['texture_name'].encode('ascii')
f.write(struct.pack('<i', len(str_bytes)))
f.write(str_bytes)
# Write invariants/unknowns
# ...
f.write(struct.pack('<i', 0xf6030000)) # f6
f.write(struct.pack('<i', self.header['num_iterations']))
for iter_data in self.iterations:
f.write(struct.pack('<i', 0xf8030000)) # f8
f.write(struct.pack('<i', 0x70170000)) # 70
f.write(struct.pack('<i', len(iter_data['distortion_spline'])))
f.write(iter_data['distortion_spline'].encode('ascii'))
# Repeat for others
# ...
f.write(struct.pack('<i', iter_data['mesh_radial_div']))
# ... add others
f.write(struct.pack('<i', 0xf9030000)) # f9
def print_properties(self):
print(f"File ID/Version: {self.header['id_version'].hex()}")
print(f"Texture Name: {self.header['texture_name']}")
print(f"Number of Iterations: {self.header['num_iterations']}")
for i, iter_data in enumerate(self.iterations):
print(f"Iteration {i+1}:")
print(f" Distortion Spline: {iter_data['distortion_spline']}")
# Print others...
print(f" Mesh Radial Division: {iter_data['mesh_radial_div']}")
# ...
if __name__ == '__main__':
if len(sys.argv) > 1:
spt = SPTFile(sys.argv[1])
spt.print_properties()
(Note: Full implementation would parse/write all splines and fields; this is a framework.)
- Java class for .SPT:
import java.io.*;
import java.nio.*;
import java.nio.charset.StandardCharsets;
import java.util.ArrayList;
import java.util.List;
public class SPTFile {
private String filename;
private ByteBuffer buffer;
private byte[] idVersion = new byte[28];
private String textureName;
private int numIterations;
private List<IterationData> iterations = new ArrayList<>();
public SPTFile(String filename) throws IOException {
this.filename = filename;
read();
}
private void read() throws IOException {
buffer = ByteBuffer.wrap(new FileInputStream(filename).readAllBytes()).order(ByteOrder.LITTLE_ENDIAN);
buffer.get(idVersion);
int strLen = buffer.getInt();
byte[] strBytes = new byte[strLen];
buffer.get(strBytes);
textureName = new String(strBytes, StandardCharsets.ASCII);
// Skip invariants/unknowns
buffer.position(buffer.position() + 4 + 4 + 4 + 1 + 4 + 4 + 4 + 4 + 4 + 4 + 4 + 4);
buffer.getInt(); // f6
numIterations = buffer.getInt();
for (int i = 0; i < numIterations; i++) {
IterationData iter = new IterationData();
buffer.getInt(); // f8
buffer.getInt(); // 70
iter.distortionSpline = parseSpline();
// Repeat for other splines
iter.meshRadialDiv = buffer.getInt();
// Add others
iterations.add(iter);
buffer.getInt(); // f9
}
}
private String parseSpline() {
int size = buffer.getInt();
byte[] bytes = new byte[size];
buffer.get(bytes);
return new String(bytes, StandardCharsets.ASCII);
}
public void write(String outFile) throws IOException {
try (FileOutputStream fos = new FileOutputStream(outFile)) {
fos.write(idVersion);
byte[] strBytes = textureName.getBytes(StandardCharsets.ASCII);
fos.write(ByteBuffer.allocate(4).order(ByteOrder.LITTLE_ENDIAN).putInt(strBytes.length).array());
fos.write(strBytes);
// Write skips
// ...
fos.write(ByteBuffer.allocate(4).order(ByteOrder.LITTLE_ENDIAN).putInt(0xf6030000).array());
fos.write(ByteBuffer.allocate(4).order(ByteOrder.LITTLE_ENDIAN).putInt(numIterations).array());
for (IterationData iter : iterations) {
fos.write(ByteBuffer.allocate(4).order(ByteOrder.LITTLE_ENDIAN).putInt(0xf8030000).array());
fos.write(ByteBuffer.allocate(4).order(ByteOrder.LITTLE_ENDIAN).putInt(0x70170000).array());
byte[] splineBytes = iter.distortionSpline.getBytes(StandardCharsets.ASCII);
fos.write(ByteBuffer.allocate(4).order(ByteOrder.LITTLE_ENDIAN).putInt(splineBytes.length).array());
fos.write(splineBytes);
// Repeat
// ...
fos.write(ByteBuffer.allocate(4).order(ByteOrder.LITTLE_ENDIAN).putInt(iter.meshRadialDiv).array());
// ...
fos.write(ByteBuffer.allocate(4).order(ByteOrder.LITTLE_ENDIAN).putInt(0xf9030000).array());
}
}
}
public void printProperties() {
System.out.println("File ID/Version: " + bytesToHex(idVersion));
System.out.println("Texture Name: " + textureName);
System.out.println("Number of Iterations: " + numIterations);
for (int i = 0; i < iterations.size(); i++) {
IterationData iter = iterations.get(i);
System.out.println("Iteration " + (i + 1) + ":");
System.out.println(" Distortion Spline: " + iter.distortionSpline);
// Print others
System.out.println(" Mesh Radial Division: " + iter.meshRadialDiv);
// ...
}
}
private static String bytesToHex(byte[] bytes) {
StringBuilder sb = new StringBuilder();
for (byte b : bytes) sb.append(String.format("%02x ", b));
return sb.toString().trim();
}
static class IterationData {
String distortionSpline;
int meshRadialDiv;
// Add other fields
}
public static void main(String[] args) throws IOException {
if (args.length > 0) {
SPTFile spt = new SPTFile(args[0]);
spt.printProperties();
}
}
}
(Note: Framework; expand for all fields.)
- JavaScript class for .SPT:
class SPTFile {
constructor(arrayBuffer) {
this.buffer = new DataView(arrayBuffer);
this.offset = 0;
this.header = {};
this.iterations = [];
this.read();
}
read() {
this.header.idVersion = this._readBytes(28).map(b => b.toString(16).padStart(2, '0')).join(' ');
this.header.textureName = this._readString(this.buffer.getInt32(this.offset, true));
this.offset += 4;
// Skip invariants
this.offset += 4 + 4 + 4 + 1 + 4 + 4 + 4 + 4 + 4 + 4 + 4 + 4;
this.offset += 4; // f6
this.header.numIterations = this.buffer.getInt32(this.offset, true);
this.offset += 4;
for (let i = 0; i < this.header.numIterations; i++) {
let iter = {};
this.offset += 4; // f8
this.offset += 4; // 70
iter.distortionSpline = this._readSpline();
// Repeat
iter.meshRadialDiv = this.buffer.getInt32(this.offset, true);
this.offset += 4;
// Add others
this.iterations.push(iter);
this.offset += 4; // f9
}
}
_readBytes(len) {
let bytes = [];
for (let i = 0; i < len; i++) {
bytes.push(this.buffer.getUint8(this.offset++));
}
return bytes;
}
_readString(len) {
let bytes = this._readBytes(len);
return new TextDecoder().decode(new Uint8Array(bytes));
}
_readSpline() {
let size = this.buffer.getInt32(this.offset, true);
this.offset += 4;
return this._readString(size);
}
write() {
// Similar to read but build ArrayBuffer; omitted for brevity
return new ArrayBuffer(0); // Placeholder
}
printProperties() {
console.log(`File ID/Version: ${this.header.idVersion}`);
console.log(`Texture Name: ${this.header.textureName}`);
console.log(`Number of Iterations: ${this.header.numIterations}`);
this.iterations.forEach((iter, i) => {
console.log(`Iteration ${i + 1}:`);
console.log(` Distortion Spline: ${iter.distortionSpline}`);
console.log(` Mesh Radial Division: ${iter.meshRadialDiv}`);
// ...
});
}
}
// Example usage:
// const file = new SPTFile(arrayBufferFromFile);
// file.printProperties();
(Note: Use with FileReader; expand parsing.)
- C class for .SPT (using C++ for class support):
#include <iostream>
#include <fstream>
#include <vector>
#include <string>
#include <iomanip>
class SPTFile {
private:
std::string filename;
std::vector<char> data;
size_t offset = 0;
std::vector<unsigned char> idVersion;
std::string textureName;
int numIterations;
struct IterationData {
std::string distortionSpline;
int meshRadialDiv;
// Add others
};
std::vector<IterationData> iterations;
public:
SPTFile(const std::string& fn) : filename(fn) {
read();
}
void read() {
std::ifstream file(filename, std::ios::binary);
file.seekg(0, std::ios::end);
size_t size = file.tellg();
file.seekg(0, std::ios::beg);
data.resize(size);
file.read(data.data(), size);
idVersion.resize(28);
std::copy(data.begin() + offset, data.begin() + offset + 28, idVersion.begin());
offset += 28;
int strLen;
std::copy(data.begin() + offset, data.begin() + offset + 4, reinterpret_cast<char*>(&strLen));
offset += 4;
textureName.assign(data.begin() + offset, data.begin() + offset + strLen);
offset += strLen;
// Skip
offset += 4 + 4 + 4 + 1 + 4 + 4 + 4 + 4 + 4 + 4 + 4 + 4;
offset += 4; // f6
std::copy(data.begin() + offset, data.begin() + offset + 4, reinterpret_cast<char*>(&numIterations));
offset += 4;
for (int i = 0; i < numIterations; ++i) {
IterationData iter;
offset += 4; // f8
offset += 4; // 70
iter.distortionSpline = parseSpline();
// Repeat
std::copy(data.begin() + offset, data.begin() + offset + 4, reinterpret_cast<char*>(&iter.meshRadialDiv));
offset += 4;
// Add others
iterations.push_back(iter);
offset += 4; // f9
}
}
std::string parseSpline() {
int size;
std::copy(data.begin() + offset, data.begin() + offset + 4, reinterpret_cast<char*>(&size));
offset += 4;
std::string spline(data.begin() + offset, data.begin() + offset + size);
offset += size;
return spline;
}
void write(const std::string& outFn) {
std::ofstream file(outFn, std::ios::binary);
file.write(reinterpret_cast<const char*>(idVersion.data()), 28);
int strLen = textureName.size();
file.write(reinterpret_cast<const char*>(&strLen), 4);
file.write(textureName.c_str(), strLen);
// Skips
// ...
int marker = 0xf6030000;
file.write(reinterpret_cast<const char*>(&marker), 4);
file.write(reinterpret_cast<const char*>(&numIterations), 4);
for (const auto& iter : iterations) {
marker = 0xf8030000;
file.write(reinterpret_cast<const char*>(&marker), 4);
marker = 0x70170000;
file.write(reinterpret_cast<const char*>(&marker), 4);
int size = iter.distortionSpline.size();
file.write(reinterpret_cast<const char*>(&size), 4);
file.write(iter.distortionSpline.c_str(), size);
// Repeat
// ...
file.write(reinterpret_cast<const char*>(&iter.meshRadialDiv), 4);
// ...
marker = 0xf9030000;
file.write(reinterpret_cast<const char*>(&marker), 4);
}
}
void printProperties() {
std::cout << "File ID/Version: ";
for (auto b : idVersion) std::cout << std::hex << std::setw(2) << std::setfill('0') << static_cast<int>(b) << " ";
std::cout << std::dec << "\n";
std::cout << "Texture Name: " << textureName << "\n";
std::cout << "Number of Iterations: " << numIterations << "\n";
for (size_t i = 0; i < iterations.size(); ++i) {
const auto& iter = iterations[i];
std::cout << "Iteration " << (i + 1) << ":\n";
std::cout << " Distortion Spline: " << iter.distortionSpline << "\n";
std::cout << " Mesh Radial Division: " << iter.meshRadialDiv << "\n";
// ...
}
}
};
int main(int argc, char** argv) {
if (argc > 1) {
SPTFile spt(argv[1]);
spt.printProperties();
}
return 0;
}
(Note: Framework; use little-endian, expand for complete fields.)