Heavy Iron Modding

EvilEngine/JSP: Difference between revisions

Page Discussion

EvilEngine/JSP (view source)

Revision as of 02:26, 2 February 2024

12,008 bytes added ,  3 months ago
→‎Version 3 (BFBB): Add visible flag and correct z-write and culling flags
Battlepedia>Igorseabra4
(Created page with "==JSP== JSP is an asset type which defines a 3D model. It's a RenderWare binary stream file. There are two types of JSP: the normal (model) has a format much similar to a DFF....")
 
(→‎Version 3 (BFBB): Add visible flag and correct z-write and culling flags)
 
(15 intermediate revisions by 4 users not shown)
Line 1:
<onlyinclude>
==JSP==
{{#vardefine:typeid|JSP}}<nowiki/>
JSP is an asset type which defines a 3D model. It's a RenderWare binary stream file. There are two types of JSP: the normal (model) has a format much similar to a DFF. They can be opened by RWAnalyze and other tools that work with RenderWare models. [https://www.gtamodding.com/wiki/RenderWare_binary_stream_file GTAModding] has a lot of useful information regarding this format. The other format is used for collision data and is very different from a normal JSP/DFF, but still follows the layout of a RenderWare binary stream file, with three custom sections.
{{#vardefine:name|JSP}}<nowiki/>
{{#vardefine:type|[[RenderWare]]}}<nowiki/>
{{#vardefine:basetype|}}<nowiki/>
{{#vardefine:games|BFBB TSSM Incredibles ROTU RatProto}}<nowiki/>
{{#vardefine:sourcecode|[https://github.com/bfbbdecomp/bfbb/blob/master/src/Core/x/xJSP.h xJSP.h]}}<nowiki/>
{{#vardefine:image|}}<nowiki/>
</onlyinclude>
{{AutoAssetInfobox}}
 
JSP is an asset type which defines a 3D model. It's a RenderWare binary stream file. There are two types of JSP: the normal (model) has a format much similar to a DFF and is stored in the BSP layer. They can be opened by RWAnalyze and other tools that work with RenderWare models. [https://gtamods.com/wiki/RenderWare_binary_stream_file GTAModding] has a lot of useful information regarding this format. The other format is used for visibility and collision data and is very different from a normal JSP/DFF, but still follows the layout of a RenderWare binary stream file with four custom sections and is stored in the JSP Info layer.
===Format (Collision JSP)===
 
// SECTION 1
===Section header format===
int 0x00BEEF01 // section type
This is the standard intformat sectionSizefor //RenderWare section sizeheaders.
 
int 0x1400FFFF // renderware version
<source lang=cpp>
char[4] CCOL
struct __rwMark
{
int amount1
unsigned int type; // section type
int amount2
unsigned int length; // section size
unknown1[amount1]
unsigned int libraryID; // renderware version
unknown2[amount2]
};
</source>
struct unknown1 {
 
int[2] unknown
==Section 1 (BSP Tree)==
float[2] unknown
This section contains a k-d tree, used for collision checking.
}
 
<source lang=cpp>
struct unknown2 {
__rwMark mark; // type = 0xBEEF01
short[2] unknown
 
byte[2] unknown
unsigned int magic;
short unknown
unsigned int numBranchNodes;
}
unsigned int numTriangles;
 
// SECTION 2
xClumpCollBSPBranchNode branchNodes[numBranchNodes];
int 0x00BEEF02 // section type
xClumpCollBSPTriangle triangles[numTriangles];
int sectionSize // section size
</source>
int 0x1400FFFF // renderware version
 
{| class="wikitable"
// big endian
! Offset !! Type !! Variable !! Description
char[4] "JSP "
|-
int unknownAmount1 // usually 3
| 0x00 || u32 || magic || "CCOL" (little-endian, PS2/XBOX)<br>"LOCC" (big-endian, GameCube)
int unknownAmount2
|-
int unknown1usually0
| 0x04 || u32 || '''numBranchNodes''' || Amount of xClumpCollBSPBranchNode entries
int unknown2usually0
|-
int unknown3usually0
| 0x08 || u32 || '''numTriangles''' || Amount of xClumpCollBSPTriangle entries
unknown3[unknownAmount2]
|-
| 0x0C || xClumpCollBSPBranchNode[] || '''branchNodes''' ||
struct unknown3{
|-
int[2] unknown
| 0x0C + (0x10*numBranchNodes) || xClumpCollBSPTriangle[] || '''triangles''' ||
}
|}
 
// SECTION 3 // GCN ONLY
 
int 0x00BEEF03 // section type
<source lang=cpp>
int sectionSize // section size
struct xClumpCollBSPBranchNode
int 0x1400FFFF // renderware version
{
unsigned int vertexCountleftInfo;
unsigned int rightInfo;
float[vertexCount][3] vertices
float leftValue;
float rightValue;
};
</source>
{| class="wikitable"
! Offset !! Type !! Variable !! Description
|-
| 0x00 || u32 || '''leftInfo''' || rowspan="2" |
* (this & 0x3) = NodeType
** 1 = Triangle
** 2 = Branch
* (this & 0xC) = Axis
** 0 = X
** 4 = Y
** 8 = Z
* (this >> 12) = Index
|-
| 0x04 || u32 || '''rightInfo'''
|-
| 0x08 || f32 || '''leftValue''' ||
|-
| 0x0C || f32 || '''rightValue''' ||
|}
 
 
<source lang=cpp>
struct xClumpCollBSPTriangle
{
unsigned short atomIndex;
unsigned short meshVertIndex;
unsigned char flags;
unsigned char platData; // BFBB
unsigned char detailed_info_cache_index // TSSM-RatProto
unsigned short matIndex;
};
</source>
{| class="wikitable"
! Offset !! Type !! Variable !! Description
|-
| 0x00 || u16 || '''atomIndex''' || Atomic index in all JSPs combined
|-
| 0x02 || u16 || '''meshVertIndex''' || Vertex index in atomic's mesh
|-
| 0x04 || u8 || '''flags''' || BFBB:
* 0x1 = Has sibling (There is another triangle after this one in memory. If not set means this is the last triangle in its chain)
* 0x2 = Counter-clockwise (This triangle is in reverse orientation (every other triangle in a tristrip mesh))
* 0x4 = Solid (This triangle has collision enabled)
* 0x8 = Visible (This triangle is visible in the world)
* 0x10 = No stand (Force the player to slide off this triangle instead of stand on it)
* 0x20 = Force receive shadows (Force this triangle to receive shadows in the world)
|-
| 0x05 || u8 || '''platData''' / '''detailed_info_cache_index''' ||
|-
| 0x06 || u16 || '''matIndex''' || Material index into the geometry's material list
|}
 
==Section 2 (JSP Info)==
This section contains rendering info for all of the RW Atomics ("nodes") in the other JSPs.
 
===Version 3 (BFBB)===
<source lang=cpp>
__rwMark mark; // type = 0xBEEF02
 
char idtag[4];
unsigned int version;
unsigned int jspNodeCount;
RpClump* clump;
xClumpCollBSPTree* colltree;
xJSPNodeInfo* jspNodeList;
 
xJSPNodeInfo jspNodeList[jspNodeCount];
</source>
{| class="wikitable"
! Offset !! Type !! Variable !! Description
|-
| 0x00 || char[4] || '''idtag''' || "JSP\0"
|-
| 0x04 || u32 || '''version ''' || Always 3 in BFBB
|-
| 0x08 || u32 || '''jspNodeCount''' || Amount of xJSPNodeInfo entries
|-
| 0x0C || u32*[3] || - || Always null (0), used internally as C++ pointers at runtime
|-
| 0x18 || xJSPNodeInfo[] || '''jspNodeList''' ||
|}
 
 
<source lang=cpp>
struct xJSPNodeInfo
{
int originalMatIndex;
int nodeFlags;
};
</source>
{| class="wikitable"
! Offset !! Type !! Variable !! Description
|-
| 0x00 || s32 || ''' originalMatIndex''' ||
|-
| 0x04 || s32 || '''nodeFlags''' || Used to toggle various rendering states:
* 0x1 - Visible (unused)
* 0x2 - Disable z-buffer write
* 0x4 - Disable back-face culling
|}
 
----
 
===Version 5 (TSSM - RatProto)===
<source lang=cpp>
__rwMark mark; // type = 0xBEEF02
 
char idtag[4];
unsigned int version;
unsigned int jspNodeCount;
RpClump* clump;
xClumpCollBSPTree* colltree;
xJSPNodeInfo* jspNodeList;
unsigned int stripVecCount;
RwV3d* stripVecList;
unsigned short vertDataFlags;
unsigned short vertDataStride;
xJSPNodeTree* nodetree;
xJSPNodeLight* nodelight;
 
xJSPNodeInfo jspNodeList[jspNodeCount];
 
int numBranchNodes;
xJSPNodeTreeBranch* branchNodes;
int numLeafNodes;
xJSPNodeTreeLeaf* leafNodes;
 
xJSPNodeTreeBranch branchNodes[numBranchNodes];
xJSPNodeTreeLeaf leafNodes[numLeafNodes];
 
//This is the same as Section 3 in BFBB
unsigned int stripVecCount;
RwV3d stripVecList[vertCount];
</source>
{| class="wikitable"
! Size(h) !! Type !! Variable !! Description
|-
| 4h || char[4] || '''idtag''' || "JSP\0"
|-
| 4h || u32 || '''version''' || Always 5
|-
| 4h || u32 || '''jspNodeCount''' || Amount of xJSPNodeInfo entries
|-
| 4h || RpClump* || '''clump''' || Always null
|-
| 4h || xClumpCollBSPTree* || '''colltree''' || Always null
|-
| 4h || xJSPNodeInfo* || '''jspNodeList''' || Always null
|-
| 4h || u32 || '''stripVecCount''' || Always null
|-
| 4h || RwV3d* || '''stripVecList''' || Always null
|-
| 2h || u16 || '''vertDataFlags''' || Always null
|-
| 2h || u16 || '''vertDataStride''' || Always null
|-
| 4h || xJSPNodeTree* || '''nodetree''' || Always null
|-
| 4h || xJSPNodeLight* || '''nodelight''' || Always null
|-
| 8h * jspNodeCount || xJSPNodeInfo[] || '''jspNodeList''' || Array of xJSPNodeInfo entries
|-
| 4h || s32 || '''numBranchNodes''' || Amount of xJSPNodeTreeBranch entries
|-
| 4h || xJSPNodeTreeBranch* || '''branchNodes''' || Always null
|-
| 4h || s32 || '''numLeafNodes''' || Amount of xJSPTreeLeaf entries
|-
| 4h || xJSPNodeTreeLeaf* || '''leafNodes''' || Always null
|-
| 10h * numBranchNodes || xJSPNodeTreeBranch[] || '''branchNodes''' || Array of xJSPNodeTreeBranch entries
|-
| 20h * numLeafNodes || xJSPNodeTreeLeaf[] || '''leafNodes''' || Array of xJSPNodeTreeLeaf entries
|-
| 4h || u32 || '''stripVecCount''' || Amount of array entries
|-
| Ch * stripVecCount || RwV3d[] || '''stripVecList''' || Vector3 array of pre-calculated vertices
|}
 
 
<source lang=cpp>
struct xJSPNodeInfo
{
int originalMatIndex;
unsigned short nodeFlags;
signed short sortOrder;
};
</source>
{| class="wikitable"
! Offset !! Type !! Variable !! Description
|-
| 0x00 || s32 || '''originalMatIndex''' ||
|-
| 0x04 || u16 || '''nodeFlags''' ||
|-
| 0x06 || s16 || '''sortOrder''' ||
|}
 
 
<source lang=cpp>
struct xJSPNodeTreeBranch
{
unsigned short leftNode;
unsigned short rightNode;
unsigned char leftType;
unsigned char rightType;
unsigned short coord;
float leftValue;
float rightValue;
};
</source>
{| class="wikitable"
! Offset !! Type !! Variable !! Description
|-
| 0x00 || u16 || '''leftNode''' ||
|-
| 0x02 || u16 || '''rightNode''' ||
|-
| 0x04 || u8 || '''leftType''' ||
|-
| 0x05 || u8 || '''rightType''' ||
|-
| 0x06 || u16 || '''coord''' ||
|-
| 0x08 || f32 || '''leftValue''' ||
|-
| 0x0C || f32 || '''rightValue''' ||
|}
 
 
<source lang=cpp>
struct xJSPNodeTreeLeaf
{
int nodeIndex;
int leafCount;
RwBBox box;
};
 
struct RwBBox
{
RwV3d sup;
RwV3d inf;
};
</source>
{| class="wikitable"
! Offset !! Type !! Variable !! Description
|-
| 0x00 || s32 || '''nodeIndex''' ||
|-
| 0x04 || s32 || '''leafCount''' ||
|-
| 0x08 || RwBBox || '''box''' ||
|}
 
==Section 3 (Pre-calculated Vertices, BFBB GCN only)==
This section contains a list of vertices extracted from every mesh in every JSP's atomic combined. This is used for collision checking on BFBB GameCube only.
<source lang=cpp>
__rwMark mark; // type = 0xBEEF03
 
unsigned int vertCount;
RwV3d verts[vertCount];
</source>
 
<source lang=cpp>
struct RwV3d
{
float x, y, z;
};
</source>
 
==Section 4 (Extra Info)==
Not present in BFBB.
 
<source lang=cpp>
__rwMark mark; // type = 0xBEEF04
 
char idtag[4] = "JSPX";
xBox bounds;
</source>
 
<source lang=cpp>
struct xBox
{
xVec3 upper;
xVec3 lower;
};
</source>
 
==Jason Hoerner's information on the custom JSP==
 
JSP is actually self-named after me. It stands for “Jason Space Partition”, a replacement for the “Binary Space Partition” supported by RenderWare. It was based on RenderWare’s BSP format, but the key difference was that my version referenced external data also used for rendering, rather than storing a complete separate copy, saving memory. And I wrote more efficient tool code to generate it, and runtime intersection code, but that’s more of an optimization, rather than something that directly affects how the format works.
The BSP/JSP format itself is a KD tree with overlap regions, used for spatial queries (like player collision or shadow intersection). You can look up how a KD tree works on Wikipedia or whatever – I’ll try to explain the specifics of the overlap regions. Here’s a diagram:
[[File:Jason space partitioning.png]]
The overlap region is defined by a pair of axis aligned planes (you’ll probably see two floating point numbers, kind of close to one another), which divide space into three regions, left, right, and overlap. There is another value (probably 0,1,2 integer) that selects which axis it represents. The blue triangles all go in the right branch of the KD tree, while the green triangles all go in the left branch.
When doing a spatial query, if your query is entirely to the right of right plane, you only need to go down the right branch of the tree. If your query is entirely to the left of the left plane, you only go down the left branch. If your query touches the overlap region, you need to go down both sides of the tree, because some triangles on both sides could be intersected. If you’re doing a long thin query (like a ray or capsule), you can clip the ray or capsule to the overlap plane before recursing (which makes it smaller for the next query).
Regarding DFF, besides the JSP replacing BSP, and some post optimizations specific to PS2 command buffers, we didn’t do anything with the DFF importer, and used what RenderWare created verbatim. So I can’t give details on the contents or import of a DFF. But hopefully those basic details of the KD tree implementation will help some.
The editor we used for the game was called the “EvilEditor”, and I didn’t do any work on it myself. It was named after Evil Dead, the first game Heavy Iron worked on, which was before I started working there. I did do a lot of work on its successor, the “GoodEditor” (which was used for all of Heavy Iron’s post RenderWare games). I can tell you all 3D geometry was built in Maya, and the EvilEditor itself was only used for object placement, setting object parameters, and scripting.
The scripting was all event based, there was no actual scripting language. Objects could send events to other objects, and an FNV hash of the string name of each object was used as an identifier for the object to send it to. Maybe searching for things that look like hashes (obviously not floats or integers) will make it obvious where events are present in the code. The game included a system where updates of distant objects were turned off for performance, including a feature where you could group objects to all update together. The “group update together” feature was used to ensure synced objects (like moving patterns of Tikis) would stay in the same pattern, and dependent objects (like teleport box pairs) would activate together.
I did the collision system. It includes an outer sphere which does “move and de-penetrate” (let the character move and go inside triangles a bit, then try to push him back out), and an inner sphere which attempts to do continuous capsule based collision, so when moving very fast, he hopefully doesn’t go through anything, but obviously speed runners have figured out how to break that! The outer sphere categorizes primitives as if the player is a cube, and picks the nearest collision along each face of the cube, and solves for where to place the character that’s outside of any collision. With lots of special cases to try to make it not jitter, and hard to get stuck (if you compare to Scooby Doo, the previous game where I didn’t do the collision, that has nasty jitter). I think Patrick has a second smaller sphere for the head, but I’m not sure…
Anyway, that’s the stuff I thought of for now, I’ll let you know if I think of anything else interesting…
--Jason
 
{{Assets}}
{{AutoGameNavs}}
 
[[Category:Asset]]
Retrieved from "https://heavyironmodding.org/wiki/Special:MobileDiff/3995...9721"