VPPTSV

From Virtual Paradise Wiki
Jump to: navigation, search

VP Propdump TSV Version 1 (VPPTSV1)

Propdump format for VP designed with simplicity, flexibility and user friendliness in mind. Based on the tab-separated values format, it is intended to be a universal format for storing the object data of worlds and that is easy to modify. Every object is displayed on a line with the various parameters such as model name and locations separated by tabs, allowing a spreadsheet editor such as Microsoft Excel or OpenOffice Calc to display these parameters in cells. These can then be modified using the spreadsheet editor or just notepad.

The TSV format is very similar to CSV, with the only difference being that it uses tabs instead of commas to separate values.

Usages

The VPPTSV format could be used to store a small group of objects or as a medium to backup an entire world. It could also be useful as an intermediate format when it is necessary to perform some tasks on builds in AW or VP such as isolating builds by a certain citizen, removing builds from before a certain date, or when converting from AW propdumps.

It can make batch modifications to multiple objects a much quicker and easier task in both AW and VP, for instance if one needs to modify each texture on a series of objects or move a build to a different location, this can be done by making use of the math functions available in spreadsheet editors.

As a flexible format, it is indiscriminate against the two styles of rotation available in VP: XYZ and Axis-Angle, the former being used in AW propdumps.

AW propdumps can also be stored in this format.

File format specification

This specification is still a work in progress and may be subject to change.

Each line in a VPPTSV file is an individual object, with the data values being separated by tab characters. The magic number or header which must be the first line is "vp propdump tsv1". This is used to identify the file format and version. This header may have additional parameters.

Programs parsing the file should ignore lines that start with a hash # allowing for comments to be added such as the creation date and world. Programs creating VPPTSV propdumps should add a line naming each column for people using spreadsheet software or text editors.

VP SDK Attribute VPPTSV Attribute Data Type (C#)
VP_OBJECT_USER_ID Owner unsigned int
VP_OBJECT_TIME DateTime DateTime
VP_OBJECT_X PositionX float
VP_OBJECT_Y PositionY float
VP_OBJECT_Z PositionZ float
VP_OBJECT_ROTATION_X RotationX float
VP_OBJECT_ROTATION_Y RotationY float
VP_OBJECT_ROTATION_Z RotationZ float
VP_OBJECT_ROTATION_ANGLE RotationAngle float
VP_OBJECT_TYPE ObjectType unsigned int
VP_OBJECT_MODEL Model string
VP_OBJECT_DESCRIPTION Description string
VP_OBJECT_ACTION Action string
VP_OBJECT_DATA ObjectData byte[]

Newline must be replaced with \n and tab must be replaced with \t
Please be aware the header version may be incremented to 1.1 if a small update is made to the specification, instead of whole numbers. This should be accounted for if your program will be processing the version number.
File extension can be .TSV or .CSV

Sample

You can copy and paste this sample into spreadsheet software to better visualise it.

vp propdump tsv1 en-GB
# Created:	09/03/2013 23:43:53
# World:	Blizzard

#Owner	DateTime	PositionX	PositionY	PositionZ	RotationX	RotationY	RotationZ	RotationAngle	ObjectType	Model	Description	Action	ObjectData
104	09/03/2013 22:49:39	-1.136963	8.195639E-09	0.2480469	0	1	0	0	0	tbtree003.rwx		create ambient .5,diffuse .5,specular 0
104	09/03/2013 23:13:00	-0.105957	0.005000007	-0.8530273	0	1	0	0	0	pp16w2.rwx		create scale .7 .6 .6,color 0;activate move -1 0 0 wait=10
104	09/03/2013 23:12:46	0.03393555	0.005000007	-0.8530273	0	1	0	0	0	pp16w2.rwx		create scale .7 .6 .6,color 0;activate move 1 0 0 wait=10
104	09/03/2013 23:15:24	0.2128906	0.101	-0.001953125	0.7700768	0.3189757	0.552482	1.286658	0	pole1m02.rwx		create visible no,solid no,light color=skyblue
104	09/03/2013 23:05:52	0.2141113	6.705522E-09	0.1479492	0	1	0	0	0	thseb1g.rwx		
104	09/03/2013 23:14:05	0.2128906	0.301	0.0480957	0	1	0	0	0	thsed2.rwx		
104	09/03/2013 23:11:47	0.4628906	0.301	1.148926	0	1	0	0	0	sign3.rwx	Cheap Test House\nfor example purposes only	create sign	
104	09/03/2013 23:15:36	0.3640137	6.705522E-09	1.398926	0	1	0	3.141593	0	mailbox1.rwx		
104	09/03/2013 23:15:42	0.2141113	6.705522E-09	1.148926	0	1	0	0	0	doorpic2.rwx		create scale .9,solid no

Date & Time Structure

The date and time structure should be compatible with most spreadsheet software, allowing the end-user to modify the propdump and perform operations such as removing objects built before a certain date. Due to the use of the DateTime function, there must be tolerance for slight alterations by spreadsheet software, so it is advised that your program will be able to understand various DateTime formats. The culture is an optional part of the header and dates will be parsed using the "en-GB" culture by default in Nexus Bot if none is specified.

The DateTime string can be parsed into a DateTime structure when programming in a .NET language using the DateTime.Parse Method. This method accepts many date & time formats making it very flexible. When using the SDK, it is easy to parse the DateTime string directly into a VpObject structure using this method.

If the culture and therefore the date format is different, this must be specified in the header as a parameter, e.g: vp propdump tsv1 en-US

This culture is only relevant to the date format, decimal points are kept the same. "en-GB" is the default culture format. Users working with spreadsheet software may decide to edit the culture to match the format of date they prefer, while working with the propdump.

The timezone to be used for converting back to a Unix Timestamp when building the propdump is UTC. This keeps the date correct.

ObjectData Format

ObjectData bytes are to be converted to Base64. Conversion to Base64 in .NET can be done using the Convert.ToBase64String and Convert.FromBase64String methods.


See also

External links

  • OpenOffice Calc - Free open-source spreadsheet software that can edit TSV files