b3d reader

The b3d module provides a method to read and write b3ds, as well as understand their contents.

Reading a .b3d

Writing a .b3d

The structure of a b3d parsed to a lua table

general structure:

for models with ONE mesh, we find that typically (at least through GreenXenith's exporter [link])
the b3d will be in the given structure, where the mesh is in the root node.

version
textures
brushes
root node (mesh)
  node (root bone)
    node (child bone)

we see, however, with multiple meshes, that we have a structure as such:

version
textures
brushes
root node
  node (mesh)  
    node (root bone) 
      node (child bone) 
  node (mesh)  
    node (rot bone) 
      node (child bone) 

if you missed it, the difference being that the root bone itself is a mesh bone. This means that when we have one unparented mesh, it'll default as the root bone.

It's also important to note that ALL bones show up in ALL "unparented" meshes, they just don't have anything in their "bone table" (see Bones as Nodes).

Nodes

Nodes are what makes up the structure of a b3d, there's really only a few things outside of nodes that exist [link], and that's above the root nodes. A node may contain several different tables containing attributes, however typically there's only really three types of nodes with their own different tables they use for our intents and purposes.

There's the root node the bone node and the mesh node. The root node (as we've seen) may be it's own sort of empty structure, or a mesh.

Before those types are mentioned, I suggest you read this general information.

A node will always contain these things

• keys
  a list of keyframes for the node.
• children
  a list of child nodes, this makes up the structure
• position
  a Vec3 containing position relative to the parent node
• rotation
  a Vec4 (quaternion) rotation relative to the parent node
• name
  a string containing the name. "ROOT" is for the root node (if multi-meshed)

Keyframes (keys)

keyframes are data structures that tell us about the animations of a node. They're fairly simple in concept, they contain a 3 vectors and the frame it represents "frame". Like the position, scale and rotation property in a node, these in the keyframe are all relative to the parent node, it's not "added" to the position and rotation property of the node that the table is present in, it replaces those default values.

a simple empty keyframe table, the index in the table starts with the lowest frame.

position = {0,0,0}
rotation = {0,0,0,1} -- a null frame
scale = {1,1,1}
frame = 0

also note that (for some forsaken reason) Green's b3d exporter (or Modlib) populates EVERY keyframe instead of them being actual keyframes, so it's more like just regular frames.

Bone node

Bones contain the bone table. This is simply a list of vertices

Meshes as nodes

Root node

The node is at the forefront of the entire, it will typically contain a mesh