SKP File Format Reference¶

This document describes the modern ZIP/VFF .skp format emitted by SketchUp 2021 and later in the observed save-version matrix. For the earlier CArchive format, see Old Binary Format.

The authoritative machine-readable tag map is in ../skp_tags.yaml.

Container Layout¶

An .skp file is a ZIP archive preceded by a text header:

+-------+
|  Text Header (UTF-16-like bytes)    |
|  - "SketchUp Model"                 |
|  - Version string "{major.minor.build}" |
+-------+
|  ZIP Archive                        |
|  +- model.dat        (required)    |
|  +- meta/meta.dat    (optional)    |
|  +- styles/*/style.xml             |
|  \- materials/*/                   |
|      +- material.xml               |
|      \- <texture files>            |
\-------+

Text Header¶

Begins with a UTF-16LE-prefixed product string ("SketchUp Model").
Followed by a version string like "{21.0.0}".
The ZIP payload starts at the first PK\x03\x04 signature.

ZIP Entries¶

Entry	Required	Description
`model.dat`	Yes	Binary TLV stream containing the model graph
`meta/meta.dat`	No	Model metadata
`styles/*/style.xml`	No	Visual style definitions
`materials/*/material.xml`	No	Material definitions (XML)
`materials/*/<textures>`	No	Texture image files

model.dat is typically stored with deflate compression (method = 8).

`model.dat` - TLV Encoding¶

model.dat is a binary Tag-Length-Value (TLV) stream. Records are nested recursively.

Record Layout¶

+--+--+----+
|  tag     |  length  |  payload        |
|  u16 LE  |  u32 LE  |  length bytes   |
\--+--+----+

tag (u16 little-endian): Identifies the record type.
length (u32 little-endian): Byte count of the payload.
payload: Either raw data or nested TLV children.

Top-Level Structure¶

The file always begins with a single root record:

Tag	Name	Description
`0x01F4`	`model_root`	Root container for the entire model

Primitive Payload Conventions¶

Payload Size	Typical Type	Examples
1 byte	Boolean / byte flag	`0` or `1`
4 bytes	`i32` / `u32`	IDs, enums, bitmasks
8 bytes	`f64` / `i64`	Distances, angles, scales
16 bytes	2 x `f64`	UV coordinates
24 bytes	3 x `f64`	Points, vectors, axes (xyz)
32 bytes	4 x `f64`	Plane equation (abcd)
48 bytes	6 x `f64`	Bounding box (min/max triplets)
72 bytes	9 x `f64`	3x3 projection matrix
104 bytes	13 x `f64`	Transform (see below)

Variable-Length Integers¶

Many IDs, counters, and references are stored as compact little-endian integers (1-4 bytes depending on value range). A value like 6 may occupy a single byte, while larger values use 2, 3, or 4 bytes.

ID Encoding¶

IDs are commonly wrapped in a two-level structure:

0x05DC (id_wrapper)
  \- 0x05DE (id_value) -> compact little-endian integer

Some records use an extended payload form:

0x05DC (id_wrapper)
  +- 0x05DD (id_extended_payload) -> nested TLV blob
  \- 0x05DE (id_value) -> compact little-endian integer

Root Tag Map (`0x01F4` Children)¶

The root record contains these top-level blocks:

Tag	Name	Description
`0x0063`	`legacy_version_marker`	Legacy version marker (u32, observed 0)
`0x01F5`	`model_id_counter_block`	ID counter seed
`0x01F6`	`entities_block`	Root-level entities (vertices, edges, faces, instances, etc.)
`0x01F7`	`materials_block`	Material definitions
`0x01F8`	`layers_block`	Layers and layer folders
`0x01F9`	`component_definitions_block`	Component definitions
`0x01FA`	`model_camera_block`	Model camera snapshot
`0x01FB`	`rendering_options_block`	Rendering/display options
`0x01FC`	`model_view_settings_block`	Sketch axes / coordinate system
`0x01FD`	`fonts_block`	Font definitions
`0x01FE`	`text_style_block`	Text style defaults
`0x01FF`	`dimension_style_block`	Dimension style defaults
`0x0200`	`options_manager_block`	Named options providers
`0x0203`	`watermarks_block`	Watermark definitions
`0x0204`	`shadow_info_block`	Shadow/geo-reference settings
`0x0205`	`active_schemata_block`	Active schema zip-file references
`0x0206`	`styles_registry_block`	Visual styles registry
`0x0207`	`scenes_block`	Saved scenes/pages
`0x0208`	`line_styles_block`	Custom line styles
`0x0209`	`model_properties_block`	Attribute dictionaries
`0x020A`	`metadata_path_entry`	Path to `meta/meta.dat`
`0x020C`	`use_mipmaps_flag`	Mipmap usage flag
`0x020D`	`section_plane_name_index_seed`	Section plane naming counter
`0x020E`	`component_behavior_defaults_block`	Default component behaviors
`0x020F`	`default_image_reference_state`	Default image reference
`0x0210`	`environment_data_block`	Environment/lighting data
`0x0213`	`sun_data_block`	Sun data
`0x0214`	`face_reversal_migration_done_flag`	Migration flag

Entities (`0x01F6`)¶

The entities block (0x1388) contains all geometric and non-geometric objects in the model.

Entity Sub-Blocks¶

Tag	Name	Description
`0x1389`	`vertices`	Vertex positions
`0x138A`	`edges`	Edge connectivity
`0x138B`	`faces`	Face geometry with loops
`0x138C`	`component_instances`	Component instance placements
`0x138D`	`groups`	Group instances
`0x138E`	`drawing_elements_ref_pid_container`	Drawing element references
`0x1390`	`images`	Image entities
`0x1391`	`guide_lines`	Construction guide lines
`0x1392`	`guide_points`	Construction guide points
`0x1393`	`section_planes`	Section plane entities
`0x1394`	`active_section_plane_ref`	Active section plane reference
`0x1396`	`curves`	Polyline curves
`0x1397`	`arc_curves`	Arc curves
`0x1399`	`dimensions`	Dimension entities
`0x139B`	`entities_metadata_block`	Entity metadata
`0x139D`	`openings`	Opening entities
`0x139E`	`entities_sentinel`	Sentinel marker
`0x139F`	`component_state_flags`	Component state bitfield
`0x13A0`	`definition_entities_bounds`	Bounding box for definition entities

Vertices¶

Each vertex record (0x09C4) contains:

Tag	Payload	Description
`0x05DC` -> `0x05DE`	compact int	Vertex ID
`0x09C5`	3 x f64	Position (x, y, z) in inches

Edges¶

Each edge record (0x0BB8) contains:

Tag	Payload	Description
`0x07D0`	nested	Entity base (IDs, flags)
`0x0BB9`	compact int	Start vertex ID
`0x0BBA`	compact int	End vertex ID
`0x0BBB`	compact int	Optional curve ID

The entity base can include 0x07D1 for a material reference, 0x07D2 for the owning layer/tag, and 0x07D3 for the compact integer edge flag bitfield. Raw modern bits are 0x01 hidden, 0x02 casts shadows, 0x04 receives shadows, 0x08 soft, and 0x10 smooth. Public Edge.flags normalizes the three edge properties to 0x01, 0x02, and 0x04 respectively. See Edge Shading Flags for how these flags map to importer normal smoothing.

Faces¶

Each face record (0x0DAC) contains:

Tag	Payload	Description
`0x07D0`	nested	Entity base (ID, front material, layer/tag, flags)
`0x0DAD`	4 x f64	Plane equation (a, b, c, d)
`0x0DAE`	nested	Loop container
`0x0DAF`	compact int	Back-material ID

Loops (0x0DAE) contain repeated loop records (0x1194), each with edge-use entries (0x1195 -> 0x0FA0):

Tag	Payload	Description
`0x0FA1`	compact int	Edge ID
`0x0FA2`	bool	Reversed flag

Hole faces are represented as multiple loop records within the same face.

Component Instances, Groups, and Images¶

All three share a common 0x1964 instance record structure:

Tag	Payload	Description
`0x07D0`	nested	Entity base
`0x1965`	UTF-8 string	Name (optional)
`0x1966`	13 x f64	Transform matrix
`0x1967`	compact int	Definition ID
`0x1968`	16 bytes	GUID-like blob

Transform encoding (0x1966): 13 doubles in SketchUp SUTransformation storage order:

[m00, m01, m02, m10, m11, m12, m20, m21, m22, tx, ty, tz, w]

To reconstruct a row-major 4x4 matrix:

matrix = [
    [m00, m01, m02, tx],
    [m10, m11, m12, ty],
    [m20, m21, m22, tz],
    [0.0, 0.0, 0.0, w],
]

Component instance: 0x138C -> 0x1964
Group: 0x138D -> 0x1D4C -> nested 0x1964
Image: 0x1390 -> 0x1F40 -> nested 0x1964

Curves¶

Tag	Name	Description
`0x1396`	`curves`	Container -> `0x4A38` records
`0x4A39`	`edge_count`	Number of edges in curve
`0x4A3A`	`curve_polygon_flag`	Polygon flag
`0x4A3B`	`first_edge_id`	First edge ID
`0x4A3C`	`last_edge_id`	Last edge ID

Arc Curves¶

0x1397 -> 0x4C2C contains a nested 0x4A38 curve record plus arc-specific payload 0x4C2D. The payload is 16 little-endian float64 values: center (3), unit normal (3), plane distance (1), radius-scaled X axis (3), radius-scaled Y axis (3), radius (1), start angle (1), and end angle (1). Curve and arc-curve sections precede EDGES; the public SDK rejects an edge-to-curve reference when the owning curve section is serialized afterward.

Section Planes¶

0x1393 -> 0x445C with plane (0x445D), name (0x445E), and symbol (0x445F).

Construction Guides¶

Guide lines use 0x1391 -> 0x4269. Their 0x4268 field contains a nested entity base, 0x426A stores a point, a unit direction, and two parameter bounds as eight doubles, and 0x426B stores a u16 stipple pattern. Infinite lines use bounds -1e30 and +1e30.

Guide points use 0x1392 -> 0x426C, with the same nested construction/entity base, position 0x426D, optional reference position 0x426E, and its enable flag 0x426F. Construction and section entities carry layer ownership in the entity-base 0x07D2 field.

Dimensions¶

Linear dimensions use 0x1399 -> 0x5BCC with base data (0x59D8) and anchor records (0x5BCD, 0x5BCE). Each anchor contains a 0x5208 point reference: kind 0x5209, position 0x520A, and primary/secondary association wrappers 0x520B/0x520C. An association wrapper 0x53FC contains an optional leaf entity ID 0x53FD and a width-prefixed outer-to-inner instance path in 0x53FE.

These records map to the same public LinearDimension and PointReference classes used for legacy files. The parser retains text, font reference, 3-D text and arrow settings, anchors, direction vectors, mode, offset, alignment, and dimension-line position.

Radial dimensions use 0x139A -> 0x5DC0, with the same common dimension base, associated target ID 0x5DC1, curve parameter 0x5DC3, radius ratio 0x5DC4, and diameter boolean 0x5DC5. Modern writer conformance covers the associated form. The parser also retains historical inline arc payloads in 0x5DC2; no accepted modern writer representation for orphaned arcs has been confirmed.

Openings¶

0x139D -> repeated 0x7530 records with origin, axes, and flags.

Materials (`0x01F7`)¶

Binary structure:

0x01F7 -> 0x30D4 -> 0x30D5 -> repeated 0x32C8 (material records)

Each material record (0x32C8) contains:

Tag	Payload	Description
`0x32CA`	bool	Record context: global (`0`) or layer-embedded (`1`)
`0x32CB`	blob	Texture payload
`0x32CC`	UTF-8 string	Material name
`0x32CD`	compact int	Optional auxiliary value; semantics unconfirmed

0x30D6 holds the current/active material reference.

Texture, opacity, color, and PBR appearance come from the optional material XML. When that resource is absent or invalid, the parser retains TLV identity/name and uses neutral appearance defaults.

Material XML¶

Rich material data is stored in materials/<name>/material.xml inside the ZIP:

<mat:material name="Brick" type="..." workflow="..."
             colorRed="180" colorGreen="80" colorBlue="60"
             trans="0" useTrans="0" hasTexture="1">
  <mat:texture textureFilename="brick.jpg" xScale="100" yScale="100">
    <mat:image path="..." file_name="brick.jpg"/>
  </mat:texture>
  <mat:pbrMR enable_metalness="0" enable_roughness="1"
             roughnessFactor="0.5" .../>
</mat:material>

Layers (`0x01F8`)¶

0x01F8 -> 0x3A98
  +- 0x3A99: layer list -> repeated 0x3C8C
  +- 0x3A9A: active layer ID
  \- 0x3A9B: folder tree -> anonymous 0x3E80 root -> public 0x3E80 nodes

Layer record (0x3C8C):

Tag	Payload	Description
`0x05DC`	nested	ID wrapper
`0x3C8D`	UTF-8 string	Layer name
`0x3C8E`	bool	Visible flag
`0x3C8F`	nested	Inline `0x32C8` layer display material; compact ID in early variants
`0x3C90`	bitmask	Scene behavior flags
`0x3C91`	compact int	Custom line style reference

Folder nodes (0x3E80) can nest through 0x3E83. Their 0x3E84 membership payload is a packed sequence: each layer ID is preceded by a one-byte width (1-4), followed by the little-endian ID bytes.

Component Definitions (`0x01F9`)¶

0x01F9 -> 0x1770 -> 0x1771 -> repeated 0x157C

Definition record (0x157C):

Tag	Payload	Description
`0x07D0`	nested	Definition base (contains ID)
`0x1388`	nested	Definition-local entities
`0x157D`	16 bytes	GUID blob
`0x157E`	UTF-8 string	Name
`0x157F`	UTF-8 string	Description
`0x1580`	UTF-8 string	Loaded-from path
`0x1581`	compact int	Timestamp
`0x1582`	bool	Modified flag
`0x1583`	compact int	Definition type
`0x1585`	nested	Packed payload (thumbnail, etc.)
`0x1B58`	nested	Component behavior defaults

The instance-to-definition join uses 0x1967 (instance) matching the definition ID inside 0x157C -> 0x07D0 -> 0x05DC -> 0x05DE.

Camera (`0x01FA`)¶

0x01FA -> 0x34BC

Tag	Payload	Description
`0x34BD`	3 x f64	Eye position
`0x34BE`	3 x f64	Target position
`0x34BF`	3 x f64	Up vector
`0x34C0`	f64	Near clipping distance
`0x34C1`	f64	Far clipping distance
`0x34C2`	bool	Perspective flag
`0x34C3`	f64	Orthographic height
`0x34C4`	f64	Perspective FOV
`0x34C5`	f64	Aspect ratio
`0x34C6`	bool	FOV-is-height flag
`0x34C7`	bool	Legacy camera flag
`0x34C8`	UTF-8 string	Description
`0x34C9`	f64	Image width
`0x34CA`	bool	2D camera flag
`0x34CB`	f64	2D scale
`0x34CC`	f64	2D center X
`0x34CD`	f64	2D center Y
`0x34CE`	bool	Allow clipping in parallel projection

Rendering Options (`0x01FB`)¶

0x01FB -> 0x733C

Contains ~50+ fields controlling display: render mode, transparency, edge display, colors (background, foreground, highlight, face front/back, fog, sky, ground, section cuts), fog settings, ambient occlusion, photomatch, and legacy compatibility flags.

Section display record 0x7375 is a bitmask shared with legacy rendering options. Bit 0x1 controls section-plane visibility and bit 0x2 controls section-cut visibility. The public model exposes these as display_section_planes and display_section_cuts while preserving the raw section_display_mode value.

Scenes (`0x0207`)¶

0x0207 -> 0x6D60 -> 0x6D61 -> repeated 0x7148

Each scene record contains:

Tag	Description
`0x6F54`	Base scene (ID, name, description)
`0x7149`	Flags
`0x714A`	Camera snapshot
`0x714B`	Hidden entity IDs
`0x714C`	Style reference
`0x714D`	Rendering options snapshot
`0x714E`	Shadow info snapshot
`0x714F`	Axes snapshot
`0x7150`	Hidden layer IDs
`0x7151`	Active section plane IDs
`0x7152`	Show in slideshow
`0x7154`-`0x7155`	Transition/delay overrides
`0x7156`	Background image reference
`0x7158`	Thumbnail image
`0x7159`	Hidden layer folder IDs
`0x715A`-`0x715B`	Environment reference/settings
`0x715C`	Foreground image IDs

The ID stored in the base scene is preserved. Camera snapshots are decoded to the same public Camera class used by model-level cameras. Collections such as hidden entities, hidden layers, and active section planes use repeated scalar TLV records; each repeated record contributes one public reference ID.

Shadow Info / Geo-Reference (`0x0204`)¶

0x0204 -> 0x6590

Tag	Payload	Description
`0x6591`	compact int	Time
`0x6592`	bool	Daylight savings
`0x6593`	raw	City name
`0x6594`	compact int	Country
`0x6595`	f64	Longitude (degrees)
`0x6596`	f64	Latitude (degrees)
`0x6597`	f64	Timezone offset
`0x6598`	3 x f64	North direction
`0x6599`-`0x65A0`	various	Display flags, light/dark settings

Attribute Dictionaries (`0x0209`)¶

0x0209 -> 0x36B1 -> 0x36B2 (dictionary records)

Each dictionary contains:

Tag	Description
`0x36B4`	Dictionary name
`0x36B5`	Entries -> `0x36B6` (key) + `0x38A4` (typed value)

Typed values (0x38A4) carry a type code (0x38A7) and one of:

0x38A8: int32 payload
0x38A9: f64 payload
0x38AA: bool payload
0x38AD: string payload
0x38AE: nested blob

The same dictionary root can appear inside an entity’s 0x05DD extended ID payload. Named records are exposed through Entities.attribute_dictionaries_by_entity_id; definition, material, and layer records use Model.attribute_dictionaries_by_object_id. Technical records in that root, including texture projections, are handled separately and do not become empty named dictionaries.

Texture projection data is also stored in attribute dictionaries; see UV Projection.

Physical Units¶

Geometric lengths: stored in SketchUp internal units (inches).
Lat/long: degrees (f64).
Camera FOV/legacy scalar: radians.
Colors: 4-byte packed ARGB (u32, little-endian).
Timestamps: compact integer (epoch-like semantics).

Parser Gotchas¶

Not all payloads are nested TLV. Fixed-size numeric blobs (24, 32, 104 bytes) can accidentally look like valid tags if decoded heuristically.
Pseudo-tags like 0x0000 and some 0x40xx values may appear from raw f64 geometry payload bytes - always parse based on known tag semantics.
Variable-length IDs must be supported (not fixed u32 only).
Legacy (non-ZIP) SKP files cannot be read through the model.dat ZIP extraction path.

Tag Coverage¶

The tag map in ../skp_tags.yaml covers:

422 mapped tags
298 leaf tags with explicit payload/type annotations
124 container-only tags (no payload type)

Inference basis: analysis of observed .skp files with cross-check against record lengths and value distributions.