Hex Master logo Hex Master

Schema Guide

Define binary layouts with a compact, file-focused DSL.

Hex Master schemas describe endianness, named structs, scalar fields, byte ranges, arrays, repeat blocks, and offset-based sections. Run a schema at a chosen base offset to parse a file region into a structured tree with offsets, sizes, coverage reporting, and JSON export.

File type .hms
Editor Tools > Schema Editor...
Best use Custom binary headers, staged tables, animation blocks, and packed file layouts

Quick Start

What a schema contains

Required parts

  • One endianness line: endian little or endian big
  • Zero or more named struct blocks
  • Exactly one root block

Run behavior

  • The base offset is chosen when you run the schema
  • Fields parse in order
  • Later fields can refer to earlier scalar fields in the same scope
  • Repeat blocks can iterate arrays parsed earlier in the file
  1. endian little
  3. struct Entry {
  4. u32 id
  5. u16 flags
  6. u16 value
  7. }
  9. root Header {
  10. bytes[4] magic
  11. u16 version
  12. u16 entry_count
  13. Entry[entry_count] entries
  14. }

Grammar

Core forms

Scalars

  • u8, u16, u32, u64
  • i8, i16, i32, i64
  • f32, f64

Byte ranges

  • bytes[16] header
  • Useful for magic values, opaque blocks, or raw payload slices

Struct fields

  • Header header
  • Entry[count] entries
Form Meaning
u32 count Read one 32-bit unsigned integer
bytes[32] blob Read 32 raw bytes
Entry[count] entries Read an array of structs using an earlier scalar count
Entry[count] entries @table_offset Read an array from a different location in the file
Entry[count * 2] entries @base + 0x20 Use expressions in both count and offset
repeat subHeader in meshHeader.subHeaders { ... } Iterate a previously parsed array to drive a later staged section

Expressions

Supported in counts and offsets

Supported

  • Earlier scalar fields in the same scope
  • Decimal integers
  • Hex integers like 0x20
  • +, -, *, /
  • Parentheses
  • Dotted references inside repeat scopes like subHeader.faceCount

Examples

  • Entry[count + 1] entries
  • bytes[numBones * 48] pose_data
  • Section[sectionCount] sections @headerSize + 0x20

Repeat Blocks

Use staged parsing when headers describe later sections.

Form

  • repeat alias in sourcePath { ... }
  • The source must resolve to an earlier parsed array
  • The block parses sequentially at the current file position

Inside the block

  • alias refers to the current repeated item
  • Dotted references like meshHeader.subHeaders are supported
  • Counts and offsets can use values such as subHeader.vertexCount

Interaction

Using the structure tree

What it shows

  • Parsed field names and types
  • Offsets and sizes for each parsed region
  • Interpreted scalar and byte values

How to use it

  • Click a field to select that byte range in the main hex view
  • Use the tree to inspect parsed structure layout
  • Use the main hex editor itself for byte-level modifications
  • Export the current parsed tree to JSON from the Schema Editor file menu

Examples

Offset-based table

  1. endian little
  3. struct Entry {
  4. u32 id
  5. u16 flags
  6. u16 value
  7. }
  9. root Header {
  10. bytes[4] magic
  11. u16 version
  12. u16 entry_count
  13. u32 entries_offset
  14. Entry[entry_count] entries @entries_offset
  15. }

Here, entry_count controls the number of items, and entries_offset points to where the array begins relative to the selected base offset.

Examples

Character animation block with dependent transform count

  1. endian little
  3. struct Transform {
  4. f32 r00
  5. f32 r01
  6. f32 r02
  7. f32 r10
  8. f32 r11
  9. f32 r12
  10. f32 r20
  11. f32 r21
  12. f32 r22
  13. f32 px
  14. f32 py
  15. f32 pz
  16. }
  18. struct Action {
  19. u16 numBones
  20. u16 numFrames
  21. Transform[numBones * numFrames] transforms
  22. }
  24. struct Actor {
  25. u16 numAction
  26. Action[numAction] actions
  27. }
  29. root CharAni {
  30. u32 numActors
  31. Actor[numActors] actors
  32. }

This pattern is useful for animation formats where the payload count depends on more than one earlier field.

Examples

Staged mesh layout with repeat blocks

  1. endian little
  3. struct SubHeader {
  4. i32 faceCount
  5. i32 vertexCount
  6. }
  8. struct MeshHeader {
  9. i32 subMeshCount
  10. SubHeader[subMeshCount] subHeaders
  11. }
  13. struct Face {
  14. u16 a
  15. u16 b
  16. u16 c
  17. }
  19. root ItemObj {
  20. i32 numMeshes
  21. MeshHeader[numMeshes] headers
  23. repeat meshHeader in headers {
  24. repeat subHeader in meshHeader.subHeaders {
  25. Face[subHeader.faceCount] faces
  26. f32[subHeader.vertexCount] posX
  27. f32[subHeader.vertexCount] posY
  28. f32[subHeader.vertexCount] posZ
  29. }
  30. }
  31. }

This pattern is useful for formats where headers are grouped first, but the payloads they describe appear later in the file. A fuller sample is available in docs/examples/item_obj.schema.

Limits

What the current DSL does not support yet

Not supported

  • Conditional fields
  • Unions
  • Arbitrary random-access pointer chasing beyond supported offset expressions and repeat scopes
  • Named enums or bitfields

Authoring rule

  • Define dependent fields after the scalar values they depend on
  • Use repeat blocks when a later section depends on an earlier parsed array