Difference between revisions of "LVZ Format"

From ASSS Wiki
Jump to: navigation, search
m (minor fix.. needs content)
 
(13 intermediate revisions by 6 users not shown)
Line 1: Line 1:
−
Todo: Add details about the format. Teaming this up w/ the [[LVL_Format]], [[ELVL_Format]] and [[LVZ_Format]] [[RGN_Format]] formats.
+
This is a quick description of the current .lvz file format. Only Continuum .37 and higher support [[LVZ]]s. If you design a program to read or write LVZ files, please safely handle the differences of the Types for each section, since newer continuum version will add newer sections.
 +
 
 +
The first 8 bytes of every .lvz file:
 +
 
 +
<table border=1 cellpadding=3 cellspacing=1 rules=rows frame=below width=90%>
 +
<tr>
 +
<th width=15%>Length</th>
 +
<th width=15%>Name</th>
 +
<th>Description</th>
 +
</tr>
 +
<tr>
 +
<td>4-len str</td>
 +
<td>Type</td>
 +
<td>Should always be 'CONT'. This verifies you have a .lvz. If not, don't continue on. This string is not NULL ended.</td>
 +
</tr>
 +
<tr>
 +
<td>u32</td>
 +
<td>Count</td>
 +
<td>How many compressed sections are in this .lvz.</td>
 +
</tr>
 +
</table>
 +
 
 +
 
 +
 
 +
After this, if the count is greater than 0, there should be a compressed header:
 +
 
 +
<table border=1 cellpadding=3 cellspacing=1 rules=rows frame=below width=90%>
 +
<tr>
 +
<th width=15%>Length</th>
 +
<th width=15%>Name</th>
 +
<th>Description</th>
 +
</tr>
 +
<tr>
 +
<td>4-len str</td>
 +
<td>Type</td>
 +
<td>Should be 'CONT' also. If not, the compression header is bad, and do not use.</td>
 +
</tr>
 +
<tr>
 +
<td>u32</td>
 +
<td>Decompress Size</td>
 +
<td>The size of the data after it would be decompressed. This is the value you should set your out-buffer for the zlib's compression call.</td>
 +
</tr>
 +
<tr>
 +
<td>u32</td>
 +
<td>File Time</td>
 +
<td>This can either be a file time, if this compressed section is a file, or it could be 0. If 0, then is a special compressed section. The file time is the standard time_t format used by windows/unix (seconds since midnight, January 1st, 1970).</td>
 +
</tr>
 +
<tr>
 +
<td>u32</td>
 +
<td>Compressed Size</td>
 +
<td>The size of the compressed data in the .lvz. This is how many bytes you'll need to read to get your required data.</td>
 +
</tr>
 +
<tr>
 +
<td>Null-end str</td>
 +
<td>File Name</td>
 +
<td>This string is always null ended. If no file time, the File Name should be blank (just the 0x00), but do not always count on it.</td>
 +
</tr>
 +
<tr>
 +
<td><i>Varies</i></td>
 +
<td>Compressed data</td>
 +
<td>This should be the length of the Compressed size. Read this all in, and then run it through zlib's decompress function.</td>
 +
</tr>
 +
</table>
 +
 
 +
 
 +
 
 +
Once you have the decompressed data, you can take action on it, or store it for later use. The compressed header with the compressed data at the end will repeat till the number of headers equals the count (if the  .lvz is made correctly), or till the end of the file.
 +
 
 +
The decompressed data can be 1 of two types for the current .lvz format. The first type is more often found in .lvzs, and this is the file type. Files are determined by having a File Time not equal to 0, and having a File Name length not being 0. Please be warned, future formats of .lvz's may change one or the other of these checks, so a good safety feature would be that files require both of these to be true. Files are normally just saved to the proper folder and the correct file time set to it. If you do not know how to set file times, its is not 100% important for most DeBuildLevel like programs.
 +
 
 +
The only other current decompressed data type is the Object section. The object section is determined by having a File Time equal to 0 and the File Name length being 0.
 +
 
 +
'''Object section can now have two different types, though only the Screen Objects are changed'''
 +
 
 +
CLV1 is for Continuum .37+, CLV2 is Continuum .38+.
 +
 
 +
Object Section always starts with this 12 byte header:
 +
 
 +
<table border=1 cellpadding=3 cellspacing=1 rules=rows frame=below width=90%>
 +
<tr>
 +
<th width=15%>Length</th>
 +
<th width=15%>Name</th>
 +
<th>Description</th>
 +
</tr>
 +
<tr>
 +
<td>4-len str</td>
 +
<td>Type</td>
 +
<td>Can be 'CLV1' or 'CLV2'.</td>
 +
</tr>
 +
<tr>
 +
<td>u32</td>
 +
<td>Object Count</td>
 +
<td>How many object (mapobject and screenobject) definitions are in this Object Section.</td>
 +
</tr>
 +
<tr>
 +
<td>u32</td>
 +
<td>Image Count</td>
 +
<td>How many image (imageobject) definitions are in this Object Section.</td>
 +
</tr>
 +
</table>
 +
 
 +
 
 +
 
 +
'''For both of CLV1's Screen/Map object, or CLV2's Map object'''
 +
 
 +
After the Object Section header, you would loop through the Object Count reading 10 bytes at a time till you hit the Object Count. Each of these 10 byte sections are the Object definitions:
 +
 
 +
<table border=1 cellpadding=3 cellspacing=1 rules=rows frame=below width=90%>
 +
<tr>
 +
<th width=15%>Length</th>
 +
<th width=15%>Name</th>
 +
<th>Description</th>
 +
</tr>
 +
<tr>
 +
<td>u1</td>
 +
<td>Map Object</td>
 +
<td>A bool-like value. If true, this is a Map Object. If false, then is a Screen Object.</td>
 +
</tr>
 +
<tr>
 +
<td>u15</td>
 +
<td>Object ID</td>
 +
<td>The value for this object id, for use with *objon for example.</td>
 +
</tr>
 +
<tr>
 +
<td>i16</td>
 +
<td>X Coord</td>
 +
<td>The X coord value, in pixels, this object will be displayed on. More information later.</td>
 +
</tr>
 +
<tr>
 +
<td>i16</td>
 +
<td>Y Coord</td>
 +
<td>The Y coord value, in pixels.</td>
 +
</tr>
 +
<tr>
 +
<td>u8</td>
 +
<td>Image Number</td>
 +
<td>Which of the Image Definitions this object will use for its graphic.</td>
 +
</tr>
 +
<tr>
 +
<td>u8</td>
 +
<td>Layer</td>
 +
<td>Which layer it will be displayed on. Values for this later.</td>
 +
</tr>
 +
<tr>
 +
<td>u12</td>
 +
<td>Display Time</td>
 +
<td>How long will display for, in 1/10th of a second.</td>
 +
</tr>
 +
<tr>
 +
<td>u4</td>
 +
<td>Display Mode</td>
 +
<td>Which display mode this object uses. Values later.</td>
 +
</tr>
 +
</table>
 +
 
 +
 
 +
 
 +
'''CLV2's Screen Object'''
 +
 
 +
<table border=1 cellpadding=3 cellspacing=1 rules=rows frame=below width=90%>
 +
<tr>
 +
<th width=15%>Length</th>
 +
<th width=15%>Name</th>
 +
<th>Description</th>
 +
</tr>
 +
<tr>
 +
<td>u1</td>
 +
<td>Map Object</td>
 +
<td>A bool-like value. If true, this is a Map Object. If false, then is a Screen Object.</td>
 +
</tr>
 +
<tr>
 +
<td>u15</td>
 +
<td>Object ID</td>
 +
<td>The value for this object id, for use with *objon for example.</td>
 +
</tr>
 +
<tr>
 +
<td>u4</td>
 +
<td>X Type</td>
 +
<td>Which part of the screen the X coord is offset from (see OffsetTypes lower down)</td>
 +
</tr>
 +
<tr>
 +
<td>i12</td>
 +
<td>X Coord</td>
 +
<td>The X coord value, in pixels, this object will be displayed on. More info later.</td>
 +
</tr>
 +
<tr>
 +
<td>u4</td>
 +
<td>Y Type</td>
 +
<td>Same as for X</td>
 +
</tr>
 +
<tr>
 +
<td>i12</td>
 +
<td>Y Coord</td>
 +
<td>The Y coord value, in pixels.</td>
 +
</tr>
 +
<tr>
 +
<td>u8</td>
 +
<td>Image Number</td>
 +
<td>Which of the Image Definitions this object will use for its graphic.</td>
 +
</tr>
 +
<tr>
 +
<td>u8</td>
 +
<td>Layer</td>
 +
<td>Which layer it will be displayed on. Values for this later.</td>
 +
</tr>
 +
<tr>
 +
<td>u12</td>
 +
<td>Display Time</td>
 +
<td>How long will display for, in 1/10th of a second.</td>
 +
</tr>
 +
<tr>
 +
<td>u4</td>
 +
<td>Display Mode</td>
 +
<td>Which display mode this object uses. Values later.</td>
 +
</tr>
 +
</table>
 +
 
 +
 
 +
After finish looping through the Object Count, you now would loop through for the Image Count. The Image Definition are not predetermined lengths though. Image Definition:
 +
 
 +
<table border=1 cellpadding=3 cellspacing=1 rules=rows frame=below width=90%>
 +
<tr>
 +
<th width=15%>Length</th>
 +
<th width=15%>Name</th>
 +
<th>Description</th>
 +
</tr>
 +
<tr>
 +
<td>i16</td>
 +
<td>X Count</td>
 +
<td>How many columns are in this image. Used for animations.</td>
 +
</tr>
 +
<tr>
 +
<td>i16</td>
 +
<td>Y Count</td>
 +
<td>How many rows are in this image.</td>
 +
</tr>
 +
<tr>
 +
<td>i16</td>
 +
<td>Animation Time</td>
 +
<td>How long does the whole animation lasts. '''NOTE''': This is stored in 1/100th of a second ''not'' 1/10</td>
 +
</tr>
 +
<tr>
 +
<td>Null-end str</td>
 +
<td>File Name</td>
 +
<td>This will be null ended. This is which file this image uses. The file name is not required to be included with the .lvz, and maybe in another .lvz package, or a non-zone downloaded image that users place in their folders themselves. So do not expect this file to always be in this .lvz or to be in the folder.</td>
 +
</tr>
 +
</table>
 +
 
 +
And thats it. That is all that a .lvz can be. If you wish to test your program for creating a .lvz, I have created a DeBuildLevel program that follows these guidelines above to be pretty strict to how continuum will load from it. It will also stop at the first sign of trouble, and print a debug message for you to be able to use.
 +
 
 +
<pre>Layer Values:
 +
0 = BelowAll
 +
1 = AfterBackground
 +
2 = AfterTiles
 +
3 = AfterWeapons
 +
4 = AfterShips
 +
5 = AfterGauges
 +
6 = AfterChat
 +
7 = TopMost</pre>
 +
 
 +
<pre>Display Mode Values:
 +
0 = ShowAlways
 +
1 = EnterZone
 +
2 = EnterArena
 +
3 = Kill
 +
4 = Death
 +
5 = ServerControlled</pre>
 +
 
 +
<pre>Types for X/Y's (CLV2 ScreenObjects Only):
 +
0 = Normal (no letters in front)
 +
1 = C - Screen center
 +
2 = B - Bottom right corner
 +
3 = S - Stats box, lower right corner
 +
4 = G - Top right corner of specials
 +
5 = F - Bottom right corner of specials
 +
6 = E - Below energy bar & spec data
 +
7 = T - Top left corner of chat
 +
8 = R - Top left corner of radar
 +
9 = O - Top left corner of radar's text (clock/location)
 +
10 = W - Top left corner of weapons
 +
11 = V - Bottom left corner of weapons</pre>
 +
 
 +
''Document approved for release by the developer of the current .lvz format, [[PriitK]].''
 +
 
 +
 
 +
==Extra information about bit ordering==
 +
 
 +
All the data is in confusing little-endian byte ordering. Here's a layout of the data within each byte:
 +
 
 +
<pre>MapObject:
 +
0: [low 7 bits id] [1 bit mapobject]
 +
1: [high 8 bits id]
 +
2: [low 8 bits x]
 +
3: [high 8 bits x]
 +
4: [low 8 bits y]
 +
5: [high 8 bits y]
 +
6: [8 bits image num]
 +
7: [8 bits layer]
 +
8: [low 8 bits display time]
 +
9: [4 bits mode] [high 4 bits display time]</pre>
 +
 
 +
<pre>ScreenObject:
 +
0: [low 7 bits id] [1 bit mapobject]
 +
1: [high 8 bits id]
 +
2: [low 4 bits x_coord] [4 bits x_type]
 +
3: [high 8 bits x_coord]
 +
4: [low 4 bits x_coord] [ 4 bits x_type]
 +
5: [high 8 bits y_coord]
 +
6: [8 bits image num]
 +
7: [8 bits layer]
 +
8: [low 8 bits display time]
 +
9: [4 bits mode] [high 4 bits display time]</pre>
 +
 
 +
<pre>ImageObject:
 +
0: [low 8 bits x-count]
 +
1: [high 8 bits x-count]
 +
2: [low 8 bits y-count]
 +
3: [high 8 bits y-count]
 +
4: [low 8 bits displayTime]
 +
5: [high 8 bits displayTime]
 +
6+: [Null-ended string filepath]</pre>
 +
 
 +
Also note that although ini's store the display time in 1/100th seconds for map and screenobjects... they are stored in the file as 1/10th seconds. This is not true for imageobjects.
 +
 
 +
[[Category: Formats]]

Latest revision as of 16:14, 24 February 2007

This is a quick description of the current .lvz file format. Only Continuum .37 and higher support LVZs. If you design a program to read or write LVZ files, please safely handle the differences of the Types for each section, since newer continuum version will add newer sections.

The first 8 bytes of every .lvz file:

Length Name Description
4-len str Type Should always be 'CONT'. This verifies you have a .lvz. If not, don't continue on. This string is not NULL ended.
u32 Count How many compressed sections are in this .lvz.


After this, if the count is greater than 0, there should be a compressed header:

Length Name Description
4-len str Type Should be 'CONT' also. If not, the compression header is bad, and do not use.
u32 Decompress Size The size of the data after it would be decompressed. This is the value you should set your out-buffer for the zlib's compression call.
u32 File Time This can either be a file time, if this compressed section is a file, or it could be 0. If 0, then is a special compressed section. The file time is the standard time_t format used by windows/unix (seconds since midnight, January 1st, 1970).
u32 Compressed Size The size of the compressed data in the .lvz. This is how many bytes you'll need to read to get your required data.
Null-end str File Name This string is always null ended. If no file time, the File Name should be blank (just the 0x00), but do not always count on it.
Varies Compressed data This should be the length of the Compressed size. Read this all in, and then run it through zlib's decompress function.


Once you have the decompressed data, you can take action on it, or store it for later use. The compressed header with the compressed data at the end will repeat till the number of headers equals the count (if the .lvz is made correctly), or till the end of the file.

The decompressed data can be 1 of two types for the current .lvz format. The first type is more often found in .lvzs, and this is the file type. Files are determined by having a File Time not equal to 0, and having a File Name length not being 0. Please be warned, future formats of .lvz's may change one or the other of these checks, so a good safety feature would be that files require both of these to be true. Files are normally just saved to the proper folder and the correct file time set to it. If you do not know how to set file times, its is not 100% important for most DeBuildLevel like programs.

The only other current decompressed data type is the Object section. The object section is determined by having a File Time equal to 0 and the File Name length being 0.

Object section can now have two different types, though only the Screen Objects are changed

CLV1 is for Continuum .37+, CLV2 is Continuum .38+.

Object Section always starts with this 12 byte header:

Length Name Description
4-len str Type Can be 'CLV1' or 'CLV2'.
u32 Object Count How many object (mapobject and screenobject) definitions are in this Object Section.
u32 Image Count How many image (imageobject) definitions are in this Object Section.


For both of CLV1's Screen/Map object, or CLV2's Map object

After the Object Section header, you would loop through the Object Count reading 10 bytes at a time till you hit the Object Count. Each of these 10 byte sections are the Object definitions:

Length Name Description
u1 Map Object A bool-like value. If true, this is a Map Object. If false, then is a Screen Object.
u15 Object ID The value for this object id, for use with *objon for example.
i16 X Coord The X coord value, in pixels, this object will be displayed on. More information later.
i16 Y Coord The Y coord value, in pixels.
u8 Image Number Which of the Image Definitions this object will use for its graphic.
u8 Layer Which layer it will be displayed on. Values for this later.
u12 Display Time How long will display for, in 1/10th of a second.
u4 Display Mode Which display mode this object uses. Values later.


CLV2's Screen Object

Length Name Description
u1 Map Object A bool-like value. If true, this is a Map Object. If false, then is a Screen Object.
u15 Object ID The value for this object id, for use with *objon for example.
u4 X Type Which part of the screen the X coord is offset from (see OffsetTypes lower down)
i12 X Coord The X coord value, in pixels, this object will be displayed on. More info later.
u4 Y Type Same as for X
i12 Y Coord The Y coord value, in pixels.
u8 Image Number Which of the Image Definitions this object will use for its graphic.
u8 Layer Which layer it will be displayed on. Values for this later.
u12 Display Time How long will display for, in 1/10th of a second.
u4 Display Mode Which display mode this object uses. Values later.


After finish looping through the Object Count, you now would loop through for the Image Count. The Image Definition are not predetermined lengths though. Image Definition:

Length Name Description
i16 X Count How many columns are in this image. Used for animations.
i16 Y Count How many rows are in this image.
i16 Animation Time How long does the whole animation lasts. NOTE: This is stored in 1/100th of a second not 1/10
Null-end str File Name This will be null ended. This is which file this image uses. The file name is not required to be included with the .lvz, and maybe in another .lvz package, or a non-zone downloaded image that users place in their folders themselves. So do not expect this file to always be in this .lvz or to be in the folder.

And thats it. That is all that a .lvz can be. If you wish to test your program for creating a .lvz, I have created a DeBuildLevel program that follows these guidelines above to be pretty strict to how continuum will load from it. It will also stop at the first sign of trouble, and print a debug message for you to be able to use. 

Layer Values:
0 = BelowAll
1 = AfterBackground
2 = AfterTiles
3 = AfterWeapons
4 = AfterShips
5 = AfterGauges
6 = AfterChat
7 = TopMost
Display Mode Values:
0 = ShowAlways
1 = EnterZone
2 = EnterArena
3 = Kill
4 = Death
5 = ServerControlled
Types for X/Y's (CLV2 ScreenObjects Only):
 0 = Normal (no letters in front)
 1 = C - Screen center
 2 = B - Bottom right corner
 3 = S - Stats box, lower right corner
 4 = G - Top right corner of specials
 5 = F - Bottom right corner of specials
 6 = E - Below energy bar & spec data
 7 = T - Top left corner of chat
 8 = R - Top left corner of radar
 9 = O - Top left corner of radar's text (clock/location)
10 = W - Top left corner of weapons
11 = V - Bottom left corner of weapons

Document approved for release by the developer of the current .lvz format, PriitK.


Extra information about bit ordering

All the data is in confusing little-endian byte ordering. Here's a layout of the data within each byte: 

MapObject:
0: [low 7 bits id] [1 bit mapobject]
1: [high 8 bits id]
2: [low 8 bits x]
3: [high 8 bits x]
4: [low 8 bits y]
5: [high 8 bits y]
6: [8 bits image num]
7: [8 bits layer]
8: [low 8 bits display time]
9: [4 bits mode] [high 4 bits display time]
ScreenObject:
0: [low 7 bits id] [1 bit mapobject]
1: [high 8 bits id]
2: [low 4 bits x_coord] [4 bits x_type]
3: [high 8 bits x_coord]
4: [low 4 bits x_coord] [ 4 bits x_type]
5: [high 8 bits y_coord]
6: [8 bits image num]
7: [8 bits layer]
8: [low 8 bits display time]
9: [4 bits mode] [high 4 bits display time]
ImageObject:
0: [low 8 bits x-count]
1: [high 8 bits x-count]
2: [low 8 bits y-count]
3: [high 8 bits y-count]
4: [low 8 bits displayTime]
5: [high 8 bits displayTime]
6+: [Null-ended string filepath]

Also note that although ini's store the display time in 1/100th seconds for map and screenobjects... they are stored in the file as 1/10th seconds. This is not true for imageobjects.

Retrieved from "https://wiki.minegoboom.com/index.php?title=LVZ_Format&oldid=5035"