Skip to content

Home

Jump to bottom
Corey edited this page Dec 29, 2024 · 3 revisions

Yokes Object File Format Specification (*.yobj)

Table of Contents

  1. Introduction
  2. General Information
  3. File Structure Overview
  4. Detailed Structure Specifications
  5. Data Parsing Workflow
  6. Flow Diagram
  7. Additional Notes

Introduction

The Yokes Object file format (*.yobj) is utilized in the Xbox 360 game Rumble Roses XX to store comprehensive 3D object data. This includes meshes, skeletal animations, materials, vertices, weights, texture coordinates, and object_names essential for rendering in-game models. This specification provides an in-depth overview of the Yokes Object file structure, detailing each component's layout, data types, and descriptions to facilitate accurate parsing and manipulation.

General Information

  • Endianness: Big Endian
  • File Identifier: 'YOBJ' represented as 0x4A424F59
  • Primary Structures:
    • Header (YokesObject_t)
    • Pointer Offsets (PointerOffsets_t)
    • Bones (Bone_t)
    • Attachments (Object_t)
    • Meshes (Mesh_t)
      • Material Parameters (Material_t)
      • Vertex Data (Vertex_t)
        • Weights (Weight_t)
        • Texture Coordinates (TexCoord_t)
      • Faces (Face_t)
    • Textures (Texture_t)

Understanding the interrelation between these structures is crucial for accurate file parsing and data extraction.

File Structure Overview

The Yokes Object file begins with a header that outlines the overall structure, including counts and offsets to various data blocks such as pointer offsets, bones, object_names, meshes, and mesh names. Following the header, the file contains multiple data sections that are interlinked via the provided offsets. Each mesh may reference multiple materials, vertices, weights, texture coordinates, and faces, while bones define the skeletal structure for animations. Additionally, mesh names are stored separately to provide identifiers for each mesh within the object.

Detailed Structure Specifications

4.1. YokesObject Header (YokesObject_t)

The header serves as the entry point to the Yokes Object file, containing essential metadata and pointers to other data structures within the file.

Offset (Hex) Size (Bytes) Data Type Variable Name Description
0x00 4 uint32 file_id File identifier, expected value 0x4A424F59 ('YOBJ')
0x04 4 uint32 file_size Total size of the file in bytes
0x08 4 uint32 unknown_01 Unknown, typically 0
0x0C 4 uint32 pof0_offset Offset to Pointer Offsets block (PointerOffsets_t)
0x10 4 uint32 unknown_02 Unknown, typically 0
0x14 4 uint32 unknown_03 Unknown, typically 0
0x18 4 uint32 mesh_count Number of meshes contained in the file
0x1C 4 uint32 mesh_offset Offset to the Meshes block (Mesh_t[])
0x20 4 uint32 skeleton_count Number of bones in the skeleton (Bone_t[])
0x24 4 uint32 texture_count Number of mesh names
0x28 4 uint32 skeleton_offset Offset to the Bones block (Bone_t[])
0x2C 4 uint32 texture_offset Offset to the Textures block (Texture_t[])
0x30 4 uint32 object_name_offset Offset to the Attachments block (Object_t[])
0x34 4 uint32 object_name_count Number of object_names contained in the file
0x38 4 uint32 unknown_07 Unknown, typically 0
0x3C 4 uint32 unknown_08 Unknown, typically 0
0x40 4 uint32 unknown_09 Unknown, typically 0
0x44 4 uint32 unknown_10 Unknown, typically 0

Dynamic Data After Header:

  • Pointer Offsets: PointerOffsets_t structure located at pof0_offset.
  • Meshes: Array of Mesh_t structures located at mesh_offset.
  • Bones: Array of Bone_t structures located at skeleton_offset.
  • Textures: Array of Texture_t structures located at texture_offset.
  • Attachments: Array of Object_t structures located at object_name_offset.

4.2. Pointer Offsets Structure (PointerOffsets_t)

Handles the encoding and decoding of pointer offsets within the file, facilitating efficient data referencing.

Offset (Hex) Size (Bytes) Data Type Variable Name Description
0x00 4 uint32 file_id Pointer Offsets identifier, expected 0x504F4630 ('POF0')
0x04 4 uint32 count Number of encoded offsets
0x08 Variable uint8[] encoding Encoded byte array representing the offsets
... ... ... ... Additional data based on encoding and count

Encoding Scheme:

  • 1-Byte Encoding:

    • Condition: Integer value ≤ 0xFC.
    • Format: Top 2 bits 01 (0x40), followed by 6 bits of data.
    • Usage: Efficient for small offset values.

  • 2-Byte Encoding:

    • Condition: Integer value ≤ 0xFFFC.
    • Format: Top 2 bits 10 (0x80), followed by 14 bits of data.
    • Usage: Suitable for medium-sized offset values.

  • 4-Byte Encoding:

    • Condition: Integer value > 0xFFFC.
    • Format: Top 2 bits 11 (0xC0), followed by 30 bits of data.
    • Usage: Necessary for large offset values.

Decoding Process:

  1. Identify Encoding Type: Examine the top 2 bits of the first byte.
  2. Extract Data:
    • 1-Byte: Extract lower 6 bits and left-shift by 2.
    • 2-Byte: Combine the first and second bytes, clear top 2 bits, and left-shift by 2.
    • 4-Byte: Combine four bytes, clear top 2 bits, and left-shift by 2.
  3. Repeat: Continue until all encoded bytes are processed.

Functions:

  • encode(integerArray): Encodes an array of integers into the specified byte format.
  • decode(byteArray): Decodes the byte array back into the original array of integers.

Notes:

  • The PointerOffsets_t structure is crucial for managing dynamic references within the file, enabling efficient data access without redundant storage.

4.3. Bone Structure (Bone_t)

Defines a single bone within the skeletal structure for animations.

Offset (Hex) Size (Bytes) Data Type Variable Name Description
0x00 16 char[16] bone_name Name of the bone
0x10 12 float[3] bone_position Position of the bone (x, y, z)
0x1C 16 float[4] bone_rotation Rotation of the bone (x, y, z, w)
0x2C 4 int32 bone_parent Index of the parent bone (-1 if none)
0x30 12 uint32[3] unknown Unknown data
0x3C 16 float[4] bone_end End position of the bone (x, y, z, w)

Notes:

  • The bone_parent field links a bone to its parent in the skeletal hierarchy, enabling hierarchical transformations.
  • Unknown fields (unknown) may hold additional transformation data or other metadata related to the bone.

4.4. Attachments Structure (Object_t)

Defines an object_name point or object within the Yokes Object, potentially used for attaching additional models or effects.

Offset (Hex) Size (Bytes) Data Type Variable Name Description
0x00 16 char[16] name Name of the object_name
0x10 4 uint32 unknown_054 Unknown field
0x14 4 uint32 unknown_055 Unknown field
0x18 4 uint32 unknown_056 Unknown field
0x1C 4 uint32 unknown_057 Unknown field

Notes:

  • The purpose of the unknown fields (unknown_054 to unknown_057) remains undetermined and may require further investigation.

4.5. Mesh Structure (Mesh_t)

Represents a single mesh within the Yokes Object, containing information about vertices, materials, bones, weights, texture coordinates, and faces.

Offset (Hex) Size (Bytes) Data Type Variable Name Description
0x00 4 uint32 vertex_count Number of vertices in the mesh (typically 4)
0x04 4 uint32 element_count Number of elements (typically 0)
0x08 4 uint32 bone_map_count Number of bones in the bone map (typically 20)
0x0C 80 int32[20] bone_map Array of bone indices referencing Bone_t structures
0x50 4 uint32 num_bone_weights Number of bone weights per vertex
0x54 4 uint32 group_index Group index for the mesh
0x58 4 uint32 unknown_11 Unknown, typically 1
0x5C 4 uint32 vertex_buffer_offset Offset to the vertex buffer data (Vertex_t[])
0x60 4 uint32 weight_offset Offset to the bone weights data (Weight_t[])
0x64 4 uint32 texcoord_offset Offset to the texture coordinates data (TexCoord_t[])
0x68 4 uint32 unknown_14 Unknown, typically 1
0x6C 16 char[16] name Name of the mesh
0x7C 4 uint32 unknown_15 Unknown
0x80 4 uint32 unknown_16 Unknown
0x84 4 uint32 material_param_count Number of material parameters
0x88 4 uint32 material_param_offset Offset to the Material Parameters block (Material_t[])
0x8C 4 uint32 element_offset Offset to the element data (Face_t[])
0x90 4 uint32 texcoord_count Number of texture coordinates
0x94 4 uint32 unknown_21 Unknown
0x98 16 float[4] bounding_sphere Bounding sphere data (x, y, z, w)

Dynamic Data Within Mesh:

  • Material Parameters: Array of Material_t structures located at material_param_offset.
  • Vertices: Array of Vertex_t structures located at vertex_buffer_offset.
  • Bone Weights: Array of Weight_t structures located at weight_offset.
  • Texture Coordinates: Array of TexCoord_t structures located at texcoord_offset.
  • Faces: Array of Face_t structures located at element_offset.

Notes:

  • The Mesh_t structure references various substructures via offsets, enabling flexible and dynamic data management within the file.
  • Unknown fields (unknown_11, unknown_14, unknown_15, unknown_16, unknown_21) may require further investigation to determine their exact purposes.

4.5.1. Material Parameters (Material_t)

Represents a single material parameter associated with a mesh, defining properties like color, textures, and reflection settings.

Offset (Hex) Size (Bytes) Data Type Variable Name Description
0x00 16 char[16] type Material parameter type identifier
0x10 2 uint16 unknown_50 Unknown
0x12 2 uint16 unknown_51 Unknown
0x14 Variable void* data Material parameter data, varies based on type

Material Types and Data Fields:

Depending on the type field, the data field's structure varies. Below is a table mapping each type to its corresponding data structure.

Parameter Name Type Description
g_bDiffTangent Boolean Enables or disables the use of tangent space normal mapping.
g_bDrawWrinkle Boolean Toggles the rendering of wrinkle effects on the character's skin.
g_bReflectAdd Boolean Enables or disables additional reflections on the surface (e.g., environmental reflections).
g_bUseGlow Boolean Toggles glow effects for materials (used for HDR-like glow effects).
g_bUseRefCube Boolean Enables or disables the use of a cube map for environmental reflections.
g_bUseRefRegMap Boolean Toggles the use of a reflection region map for specific material regions.
g_f2WrinkleRegU Vector2 UV region control for wrinkles along the U direction.
g_f2WrinkleRegV Vector2 UV region control for wrinkles along the V direction.
g_f4BruiseCol Vector4 RGBA color of bruises applied to the character's skin.
g_f4Fairy Vector4 Internal debug or auxiliary parameter, possibly unused or experimental.
g_f4FairyColorC Vector4 Color control for internal or auxiliary fairy-like effects (debug/placeholder).
g_f4FairyColorO Vector4 Secondary color control for fairy-like effects.
g_f4FairyLv Vector4 Intensity levels for fairy-like effects (likely not used in final rendering).
g_f4MatAmbCol Vector4 Material ambient color (RGBA). Controls the ambient light response of the material.
g_f4MatDifCol Vector4 Material diffuse color (RGBA). Determines the primary shading color under lighting.
g_f4Scale Vector4 General scale control for materials, potentially affecting tiling or texture scaling.
g_f4SpecularCol Vector4 Material specular color (RGBA). Determines the color and intensity of specular highlights.
g_f4TileEffVal Vector4 Values controlling texture tiling effects (e.g., scaling, displacement).
g_fAmbOccDif Float Diffuse contribution from ambient occlusion.
g_fAmbOccLev Float Ambient occlusion intensity level.
g_fBruiseLev Float Intensity level of bruises on the character's skin.
g_fHDRAlpha Float Intensity of HDR-like effects on the material (brightness multiplier).
g_fNoizeSpeed Float Speed of noise effects, potentially for water or sweat rendering.
g_fReflectAlpha Float Reflection transparency. Higher values make reflections more subtle.
g_fScrollU, g_fScrollV Float UV scrolling parameters for animated textures (e.g., sweat or water movement).
g_fScrollU2 to g_fScrollV4 Float Secondary UV scrolling layers for multi-layered texture animations.
g_fSL_Scale Float Scale factor for surface-level effects, such as fine normal details.
g_fSpecularLev Float Intensity of specular highlights.
g_fSweatLev Float Intensity of sweat effects.
g_fSweatSPA Float Specular intensity adjustment for sweat effects.
g_fTileCountU, g_fTileCountV Float Number of times textures are tiled along U and V axes.
g_fTileEffSw Float Switch or intensity control for tiling effects.
g_fvLightLimit Vector4 Limits for light contribution to the material.
g_fWaveSpeed Float Speed of wave-like effects, potentially for water or fabric physics.
g_fWrinkleBlend Float Blend intensity for wrinkle effects.
g_iBruiseParts Integer Index or ID for the part of the body where bruises are applied.
g_iSpecularPow Integer Power (sharpness) of specular highlights.
g_iWrinkleParts Integer Index or ID for the part of the body where wrinkles are applied.
g_texDiffuse Texture Index Index of the diffuse texture map.
texCubeRefction Texture Index Index of the cube map used for reflections.
texDiffuse Texture Index Duplicate or secondary diffuse texture index.
texNoizeMap Texture Index Index of the noise texture map.
texNormal Texture Index Index of the normal map texture.
texOcclusion Texture Index Index of the ambient occlusion texture map.
texRefctionReg Texture Index Index of the reflection region map.
texSpecularMap Texture Index Index of the specular map texture.
texSphRefction Texture Index Index of a spherical reflection map.
texTilingMap Texture Index Index of the texture used for tiling effects.
texUVScroll to texUVScroll4 Texture Index Indices of textures with animated UV scrolling.
texWrinkleMap Texture Index Index of the texture used for wrinkle effects.

Note: Unknown types encountered during parsing should be documented for future reference.

4.5.2. Vertex Data (Vertex_t)

Defines a single vertex within a mesh, including its position, normal vector, and color.

Offset (Hex) Size (Bytes) Data Type Variable Name Description
0x00 12 float[3] position Vertex position (x, y, z)
0x0C 12 float[3] normal Vertex normal vector (x, y, z)
0x18 4 uint8[4] color Vertex color (r, g, b, a)

Notes:

  • The position and normal vectors are essential for rendering and lighting calculations.
  • The color field may be used for vertex coloring or other visual effects.
4.5.2.1. Weights (Weight_t)

Represents a single bone weight associated with a vertex, defining the influence of a bone on that vertex.

Offset (Hex) Size (Bytes) Data Type Variable Name Description
0x00 4 int32 bone_id Identifier of the bone
0x04 4 float weight Weight of the bone's influence

Structure:

  • Array: Multiple Weight_t structures are stored sequentially based on num_bone_weights for each vertex.

Note: The bone_id references the index of a bone in the Bone_t array, and weight represents the degree of influence that bone has on the vertex.

4.5.2.2. Texture Coordinates (TexCoord_t)

Defines a single texture coordinate associated with a vertex, mapping the vertex to a point on a texture.

Offset (Hex) Size (Bytes) Data Type Variable Name Description
0x00 4 float u U-coordinate
0x04 4 float v V-coordinate

Structure:

  • Array: Multiple TexCoord_t structures are stored sequentially based on texcoord_count.

Note: Texture coordinates are used to map textures accurately onto the mesh surfaces.

4.5.3. Faces (Face_t)

Represents a single face (polygon) within a mesh, including its type, count, and indices.

Offset (Hex) Size (Bytes) Data Type Variable Name Description
0x00 4 uint32 type Type identifier for the face
0x04 4 uint32 face_count Number of faces
0x08 4 uint32 face_offset Offset to the face indices array
0x0C Variable uint16[] faces Array of face indices (variable length)

Note: The faces array contains uint16 indices referencing vertices in the Vertex_t array.

4.6. Textures Structure (Texture_t)

Represents the names associated with each mesh within the Yokes Object. Each mesh name is a fixed-length string of 16 characters.

Offset (Hex) Size (Bytes) Data Type Variable Name Description
0x00 16 char[16] texture Name of the mesh

Structure:

  • Array: Multiple Texture_t structures are stored sequentially based on texture_count.

Note: Mesh names are essential for identifying and referencing individual meshes within the object, especially when applying materials or animations.

5. Data Parsing Workflow

To accurately parse a Yokes Object (*.yobj) file, follow the sequence below:

  1. Initialize File Parsing:

    • Open the file in binary mode.
    • Set the reading mode to big endian.

  2. Read Header (YokesObject_t):

    • Verify file_id is 0x4A424F59 ('YOBJ').
    • Extract all header fields based on the YokesObject_t structure.

  3. Read Pointer Offsets (PointerOffsets_t):

    • Seek to pof0_offset.
    • Read and decode the pointer offsets using the PointerOffsets_t structure.

  4. Read Bones (Bone_t[]):

    • Seek to skeleton_offset.
    • Iterate skeleton_count times to read each Bone_t structure.

  5. Read Object Names (Object_t[]):

    • Seek to object_name_offset.
    • Iterate object_name_count times to read each Object_t structure.

  6. Read Meshes (Mesh_t[]):

    • Seek to mesh_offset.
    • Iterate mesh_count times to read each Mesh_t structure.
    • For each mesh:
      • Read Material Parameter Addresses:
        • If material_param_offset > 0 and material_param_count > 0:
          • Seek to material_param_offset.
          • Read material_param_count offsets into mat_param_addrs.
          • For each address in mat_param_addrs:
            • Seek to the offset and read a Material_t structure.
          • Store all Material_t instances in mat_params.
      • Read Vertices:
        • If vertex_buffer_offset > 0 and vertex_count > 0:
          • Seek to vertex_buffer_offset.
          • Read vertex_count Vertex_t structures.
          • For each Vertex_t:
            • Read Weights:
              • If weight_offset > 0 and num_bone_weights > 0:
                • Seek to weight_offset.
                • Read num_bone_weights Weight_t structures.
                • Store in bone_weights.
            • Read Texture Coordinates:
              • If texcoord_offset > 0 and texcoord_count > 0:
                • Seek to texcoord_offset.
                • Read texcoord_count TexCoord_t structures.
                • Store in texcoords.
      • Read Faces:
        • If element_offset > 0 and element_count > 0:
          • Seek to element_offset.
          • Read element_count Face_t structures.
          • For each Face_t:
            • Seek to face_offset and read face_count uint16 indices.
            • Store in faces.

  7. Read Texture Names (Texture_t[]):

    • Seek to texture_offset.
    • Iterate texture_count times to read each Texture_t structure.

  8. Process Dynamic Data:

    • Use the decoded pointer offsets to locate and parse additional dynamic data as needed.

  9. Finalize Parsing:

    • Ensure all data blocks are read correctly.
    • Handle any remaining unknown fields appropriately.

6. Flow Diagram

The following text-based flow diagram illustrates the hierarchical structure and relationships between various data blocks within the Yokes Object (*.yobj) file for Rumble Roses XX. This diagram provides a visual representation of how different data structures are organized and interconnected via offsets.

+---------------------------+
|       YokesObject_t       |  Root Header (72 Bytes)
|---------------------------|
| fileid        [YOBJ]      |    +---------------------------+
| filesize                  |    |    PointerOffsets_t       |  POF0 Block (8 + n Bytes)
| unk01                     |    |---------------------------|
| pof0_offset               |--->| fileid         [POF0]     |
| mesh_count                |    | count                     |
| mesh_offset               |    | encoding[ ]               |
| skel_count                |    | offsets[ ]                |
| skel_offset               |    +---------------------------+
| texture_count           |
| texture_offset          |
| object_name_count          |
| object_name_offset         |
+---------------------------+
              |
              +-----------------------------------+
              |                                   |
              |                                   |
              |                   +-------------------------------+
              |                   |                               |
              |                   v                               v
              |     +---------------------------+     +---------------------------+
              |     |        Bone_t[ ]          |     |      Object_t[ ]          |
              |     |---------------------------|     |---------------------------|
              |     | bone_name[16]             |     | name[16]                  |
              |     | bone_position[3]          |     | unk054                    |
              |     | bone_rotation[4]          |     | unk055                    |
              |     | bone_parent               |     | unk056                    |
              |     | unknown[3]                |     | unk057                    |
              |     | bone_end[4]               |     +---------------------------+
              |     +---------------------------+
              |
              +----------------------------------------------------+
              |                                                    |
              v                                                    v
+---------------------------+                         +---------------------------+
|        Mesh_t[ ]          |                         |      Textures           |
|---------------------------|                         |---------------------------|
| vertex_count              |                         | name[16][texture_count] |
| element_count             |                         +---------------------------+
| bone_map_count            |
| bone_map[20]              |   <----------------------- References mesh names
| mat_param_count           |
| mat_param_offset          |
| vertex_buf_offset         |
| texcoord_offset           |
| weight_offset             |
| element_offset            |
+---------------------------+
              |
              +----------------------------------------------------+
              |                                                    |
              v                                                    v
+---------------------------+                         +---------------------------+
|        Material_t[ ]      |                         |        Vertex_t[ ]        |
|---------------------------|                         |---------------------------|
| type                      |                         | position[3]               |
| unk50                     |                         | normal[3]                 |
| unk51                     |                         | colour[4]                 |
| data                      |                         +---------------------------+
+---------------------------+                                       |
              |                                                     v
              v                                       +---------------------------+
+---------------------------+                         |      Weights              |
|        Parameter_t[ ]     |                         |---------------------------|
|---------------------------|                         | bone_ids[ ]               |
| type                      |                         | bone_weights[ ]           |
| data                      |                         +---------------------------+
+---------------------------+                                       |
                                                                    v
                                                      +---------------------------+
                                                      |        UVs                |
                                                      |---------------------------|
                                                      | texcoords[texcoord_count] |
                                                      |                           |
                                                      +---------------------------+
                                                                    |
                                                                    v
                                                      +---------------------------+
                                                      |       Face_t[ ]           |  Faces/Elements
                                                      |---------------------------|
                                                      | type                      |
                                                      | face_count                |
                                                      | face_offset               |
                                                      | faces[ ]                  |
                                                      +---------------------------+

7. Additional Notes

  • Unknown Fields: Several fields within the structures are labeled as unknown due to insufficient information. Further analysis, such as reverse engineering or in-game testing, may be required to determine their exact purposes.

  • Variable-Length Data: Structures like Mesh_t and PointerOffsets_t contain arrays with lengths defined by preceding count fields. Ensure accurate parsing by adhering to the count and offset specifications.

  • Error Handling: Implement robust error checking to handle unexpected values, incorrect offsets, or corrupted data gracefully.

  • Endian Conversion: Since the file is in big endian format, ensure all multi-byte values are correctly converted to the host's endianness during parsing.

  • Extensibility: The specification is based on the provided MaxScript. Future updates to the game or additional data structures may necessitate revisions to this specification.

  • Textures Importance: Mesh names (Texture_t) provide identifiers for individual meshes, which can be crucial when applying materials, animations, or for referencing in external tools.

  • Pointer Offsets Usage: The PointerOffsets_t structure efficiently manages references within the file, reducing redundancy and optimizing memory usage.

  • Interdependencies: Understanding the relationships between different structures (e.g., how Mesh_t references Material_t, Vertex_t, Weight_t, TexCoord_t, and Face_t) is essential for accurate data manipulation and extraction.

  • Dynamic Data Grouping: The flow diagram emphasizes how dynamic data such as materials, vertices, weights, texture coordinates, and faces are grouped under each mesh, ensuring a clear hierarchical understanding of data relationships.

By adhering to this updated specification and utilizing the revised flow diagram, developers and modders can accurately parse, interpret, and manipulate Yokes Object files for Rumble Roses XX, enabling custom modifications, analysis, or tooling development.

Clone this wiki locally