Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Start a debug tool for looking through level data #954

Merged
merged 6 commits into from
Oct 31, 2021

Conversation

water111
Copy link
Collaborator

@water111 water111 commented Oct 31, 2021

This adds a tool to dump data from a level file. For now, it focuses on the drawable trees and the tfrag stuff.

The idea is that we can use this tool to learn about the tfrag format in detail before starting on the tfrag decompilation and porting. So far, I have learned the tree format for tfrag and drawables.

At the highest level is the level file itself, which is a bsp-header. It contains a drawable-tree-array, which contains a small number of drawable-trees. (~1 to 15?).

Each of these drawable-trees is a different kind, distinguished by its type. Different types of trees go to different renderers. For example, there is a drawable-tree-lowres-tfrag, a drawable-tree-instance-tie, and even a drawable-tree-actor. It is possible to have multiple trees of the same type, as some trees seem to have a maximum size - for example a drawable-tree-instance-tie can have only 43 different prototypes, so it is common to see a few of these. These trees are the thing passed to the appropriate renderers. All the trees for all the levels get put in the background-work structure, which is then read by the renderers.

The drawable-tree-tfrag contains all the "normal" tfrag data. There are other trees like trans, dirt, ice, lowres, and lowres-trans, which are only present if the level actually has this type of geometry. As far as I can tell, the special ones follow the same format, but I haven't checked this in detail.

The drawable-tree-tfrag contains a small number (1 to 6?) of drawable-inline-array. They all refer to the same set of tfragments (the actual things to draw), but have a different tree structure.

The drawable-inline-array contains draw-nodes. Each draw-node contains between 0 and 8 children. The children are represented by a pointer to an inline array of children. The children can be either draw-nodes or tfragments. All the children are always the same type.

The first drawable-inline-array in the drawable-tree-tfrag is the full tree structure. It starts with some number of children that is smaller than 8. And from there on, all children are draw-node (always 8 or fewer children) or a tfragment directly. So this is the deepest possible tree. I believe the max depth seen is 6?

The next drawable-inline-array starts with a list of all nodes at with a depth of 1 from one of the top-level nodes of the first. So this has at most 64 entries. Like the previous tree, all the children from here on have 8 or fewer children.

This pattern continues. The n-th drawable-inline-array is a list of all nodes at depth n in the "real" tree.

There are two tricks to this:
First, if the drawable-inline-array contains draw-nodes, the type is actually drawable-inline-array-node. Unlike a draw-node, which can only contain 8 children, a drawable-inline-array can contain a huge number of children. The final drawable-inline-array is a list of a all children at the final depth, so it's always an array of tfragment. In this case, the type of the drawable-inline-array is a drawable-inline-array-tfrag, and it's just a giant list of all the tfragments in the level.

The second trick is that the draw-nodes and tfragments are stored only once, even if they appear in multiple drawable-inline-arrays. They used the weird "node = length + pointer to inline array of children" format and sorted nodes by depth to enable this.

@water111 water111 merged commit 6a606d7 into master Oct 31, 2021
@water111 water111 deleted the w/level-inspection branch October 31, 2021 17:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant