Revision as of 15:55, 23 October 2012

Introduction

There are many asset types in OpenSimulator (e.g. notecards, sounds, textures). Each of these has its own distinctive format.

On the whole, asset formats are identical to those used by the Second Life system, since they need to be sent to and understood by a second life client. You can find the details of many of those in the libopenmetaverse library that OpenSimulator uses. However, some are unique to OpenSimulator, in particular the object/prim serialization format.

Object/prim serialization formats

There are currently two object formats in OpenSimulator - 'xml' and 'xml2'. These are semantically identical and physically almost identical - by a sad quirk of fate slightly different formats are used for different purposes (e.g. serialization to asset store and storage in OAR files).

In addition, these formats evolved out of the automatic serialization of the internal SceneObjectGroup and SceneObjectPart objects (hence the names). This means that they contain some cryptic and redundant information.

'xml' format

Here's an example

<SceneObjectGroup>
  <RootPart>
    <SceneObjectPart xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
      <AllowedDrop>false</AllowedDrop>
      <CreatorID>
        <UUID>57956c4b-ff2e-4fc1-9995-613c6256cc98</UUID>
      </CreatorID>
      <FolderID>
        <UUID>b06d2e45-650e-4e5d-a08a-b03a6dd67bff</UUID>
      </FolderID>
      <InventorySerial>0</InventorySerial>
      <TaskInventory>
        <TaskInventoryItem>
          <AssetID>
            <UUID>db014308-b772-4ea4-821a-9872cb05f491</UUID>
          </AssetID>
          <BasePermissions>581632</BasePermissions>
          <CreationDate>1338276966</CreationDate>
          <CreatorID>
            <UUID>a1944ebf-4771-4524-9154-1738efe34abd</UUID>
          </CreatorID>
          <Description>2011-12-06 15:25:33 lsl2 script</Description>
          <EveryonePermissions>0</EveryonePermissions>
          <Flags>1048576</Flags>
          <GroupID>
            <UUID>00000000-0000-0000-0000-000000000000</UUID>
          </GroupID>
          <GroupPermissions>0</GroupPermissions>
          <InvType>10</InvType>
          <ItemID>
            <UUID>c1ed6809-cc24-4061-a4c2-93082a2d1f1d</UUID>
          </ItemID>
          <OldItemID>
            <UUID>db328934-68e9-471f-a72c-9a49491c0301</UUID>
          </OldItemID>
          <LastOwnerID>
            <UUID>00000000-0000-0000-0000-000000000000</UUID>
          </LastOwnerID>
          <Name>radarHUD script</Name>
          <NextPermissions>581632</NextPermissions>
          <OwnerID>
            <UUID>a1944ebf-4771-4524-9154-1738efe34abd</UUID>
          </OwnerID>
          <CurrentPermissions>581632</CurrentPermissions>
          <ParentID>
            <UUID>52641dc1-a7e9-4c5c-ac83-e5884e759f99</UUID>
          </ParentID>
          <ParentPartID>
            <UUID>52641dc1-a7e9-4c5c-ac83-e5884e759f99</UUID>
          </ParentPartID>
          <PermsGranter>
            <UUID>00000000-0000-0000-0000-000000000000</UUID>
          </PermsGranter>
          <PermsMask>0</PermsMask>
          <Type>10</Type>
          <OwnerChanged>false</OwnerChanged>
        </TaskInventoryItem>
      </TaskInventory>
      <UUID>
        <UUID>b06d2e45-650e-4e5d-a08a-b03a6dd67bff</UUID>
      </UUID>
      <LocalId>2094307979</LocalId>
      <Name>Companion cube</Name>
      <Material>3</Material>
      <PassTouches>false</PassTouches>
      <RegionHandle>1099511628032000</RegionHandle>
      <ScriptAccessPin>0</ScriptAccessPin>
      <GroupPosition>
        <X>81.85081</X>
        <Y>157.5245</Y>
        <Z>21.32862</Z>
      </GroupPosition>
      <OffsetPosition>
        <X>0</X>
        <Y>0</Y>
        <Z>0</Z>
      </OffsetPosition>
      <RotationOffset>
        <X>0</X>
        <Y>0</Y>
        <Z>0</Z>
        <W>1</W>
      </RotationOffset>
      <Velocity>
        <X>0</X>
        <Y>0</Y>
        <Z>0</Z>
      </Velocity>
      <AngularVelocity>
        <X>0</X>
        <Y>0</Y>
        <Z>0</Z>
      </AngularVelocity>
      <Acceleration>
        <X>0</X>
        <Y>0</Y>
        <Z>0</Z>
      </Acceleration>
      <Description/>
      <Color>
        <R>0</R>
        <G>0</G>
        <B>0</B>
        <A>255</A>
      </Color>
      <Text/>
      <SitName/>
      <TouchName/>
      <LinkNum>0</LinkNum>
      <ClickAction>0</ClickAction>
      <Shape>
        <ProfileCurve>1</ProfileCurve>
        <TextureEntry>iVVnRyTLQ+2SC0fK7RVGXwAAAAAAAAAAgD8AAACAPwAAAAAAAAAAAAAAAAAAAA==</TextureEntry>
        <ExtraParams>AA==</ExtraParams>
        <PathBegin>0</PathBegin>
        <PathCurve>16</PathCurve>
        <PathEnd>0</PathEnd>
        <PathRadiusOffset>0</PathRadiusOffset>
        <PathRevolutions>0</PathRevolutions>
        <PathScaleX>100</PathScaleX>
        <PathScaleY>100</PathScaleY>
        <PathShearX>0</PathShearX>
        <PathShearY>0</PathShearY>
        <PathSkew>0</PathSkew>
        <PathTaperX>0</PathTaperX>
        <PathTaperY>0</PathTaperY>
        <PathTwist>0</PathTwist>
        <PathTwistBegin>0</PathTwistBegin>
        <PCode>9</PCode>
        <ProfileBegin>0</ProfileBegin>
        <ProfileEnd>0</ProfileEnd>
        <ProfileHollow>0</ProfileHollow>
        <State>0</State>
        <ProfileShape>Square</ProfileShape>
        <HollowShape>Same</HollowShape>
        <SculptTexture>
          <UUID>00000000-0000-0000-0000-000000000000</UUID>
        </SculptTexture>
        <SculptType>0</SculptType>
        <SculptData/>
        <FlexiSoftness>0</FlexiSoftness>
        <FlexiTension>0</FlexiTension>
        <FlexiDrag>0</FlexiDrag>
        <FlexiGravity>0</FlexiGravity>
        <FlexiWind>0</FlexiWind>
        <FlexiForceX>0</FlexiForceX>
        <FlexiForceY>0</FlexiForceY>
        <FlexiForceZ>0</FlexiForceZ>
        <LightColorR>0</LightColorR>
        <LightColorG>0</LightColorG>
        <LightColorB>0</LightColorB>
        <LightColorA>1</LightColorA>
        <LightRadius>0</LightRadius>
        <LightCutoff>0</LightCutoff>
        <LightFalloff>0</LightFalloff>
        <LightIntensity>1</LightIntensity>
        <FlexiEntry>false</FlexiEntry>
        <LightEntry>false</LightEntry>
        <SculptEntry>false</SculptEntry>
      </Shape>
      <Scale>
        <X>0.5</X>
        <Y>0.5</Y>
        <Z>0.5</Z>
      </Scale>
      <SitTargetOrientation>
        <X>0</X>
        <Y>0</Y>
        <Z>0</Z>
        <W>1</W>
      </SitTargetOrientation>
      <SitTargetPosition>
        <X>0</X>
        <Y>0</Y>
        <Z>0</Z>
      </SitTargetPosition>
      <SitTargetPositionLL>
        <X>0</X>
        <Y>0</Y>
        <Z>0</Z>
      </SitTargetPositionLL>
      <SitTargetOrientationLL>
        <X>0</X>
        <Y>0</Y>
        <Z>0</Z>
        <W>1</W>
      </SitTargetOrientationLL>
      <ParentID>0</ParentID>
      <CreationDate>1325896997</CreationDate>
      <Category>0</Category>
      <SalePrice>0</SalePrice>
      <ObjectSaleType>0</ObjectSaleType>
      <OwnershipCost>0</OwnershipCost>
      <GroupID>
        <UUID>00000000-0000-0000-0000-000000000000</UUID>
      </GroupID>
      <OwnerID>
        <UUID>57956c4b-ff2e-4fc1-9995-613c6256cc98</UUID>
      </OwnerID>
      <LastOwnerID>
        <UUID>57956c4b-ff2e-4fc1-9995-613c6256cc98</UUID>
      </LastOwnerID>
      <BaseMask>2147483647</BaseMask>
      <OwnerMask>2147483647</OwnerMask>
      <GroupMask>0</GroupMask>
      <EveryoneMask>0</EveryoneMask>
      <NextOwnerMask>2147483647</NextOwnerMask>
      <Flags>None</Flags>
      <CollisionSound>
        <UUID>00000000-0000-0000-0000-000000000000</UUID>
      </CollisionSound>
      <CollisionSoundVolume>0</CollisionSoundVolume>
      <TextureAnimation/>
      <ParticleSystem/>
      <PayPrice0>-2</PayPrice0>
      <PayPrice1>-2</PayPrice1>
      <PayPrice2>-2</PayPrice2>
      <PayPrice3>-2</PayPrice3>
      <PayPrice4>-2</PayPrice4>
    </SceneObjectPart>
  </RootPart>
  <OtherParts/>
  <GroupScriptStates>
    <!-- A large amount of scripting data comes here.  Please see later sections -->
  </GroupScriptStates>
</SceneObjectGroup>

Explanation

TODO: Need to add more properties. Please feel free to ask on the opensim-dev mailing list for more explanation.

<SceneObjectGroup> - Each object in OpenSimulator is a group of prims, otherwise known as a link set.

<RootPart> - One prim is always the root prim (here referred to as the root part. Other prims will be in the OtherParts section but will have exactly the same format as the root SceneObjectPart.

<SceneObjectPart> - This contains all the individual prim properties.

<CreatorID> - The creator of the prim. Each user in OpenSimulator has their own unique id (UUID).

<TaskInventory> - This contains data on each item within the object, one to each <TaskInventoryItem>. TODO: Need to add separate explanation of components in this section.

<UUID> - If this is the outer property (i.e. isn't a <UUID> within a different property), then this is the ID of the part itself.

<LocalId> - The local id is a temporary id given to a prim when it's within a scene. It plays no useful role in the external format and one day should be eliminated.

<Name> - The name of the part

<RegionHandle> - The region that the part was in when it was last serialized. Again, this has no use in an external format.

<GroupPosition> - The position that a prim occupied in a region. <X>, <Y> and <Z> are the co-ordinates in three dimension space.

<OffsetPosition> - The offset of this prim from the root prim. For a root prim this will always be 0, 0, 0

<RotationOffset> - The rotation compared to the rotation of the root prim. This is in quaternion format where the components are <X>, <Y>, <Z> and <W>.

<Velocity> - The velocity of the prim in the scene.

<AngularVelocity> - The angular velocity of the prim in the scene.

<Acceleration> - The acceleration of the prim in the scene.

<Description> - The description field of the prim.

<Color> - The color of the prim. This is expressed as a 0-255 value of red <R>, green <G>, blue <B> and alpha <A>, where alpha = 0 is fully transparent.

<Text> - The text that hovers over the prim in-world

<LinkNum> - The number of this prim in the SceneObjectGroup (linkset). The root prim will always have LinkNum = 0. Subsequent prims will have consecutive numbers, 1, 2, 3 ...

<Shape> - Shape details of the prim, e.g. taper, profile shape, etc. Essentially, all those properties that you see in the edit box of a client

<TextureEntry> - An encoded field which contains all the texture references for faces of the prim. This is encoded because it's a direct copy of the on-the-wire format. See the TextureEntry class in libopenmetaverse for more details on how to decode/encode. That in itself ain't pretty.

<SculptTexture> - If this prim is a sculpt or mesh, then this refers to the sculpt texture or mesh asset that defines its shape.

<Scale> - The scale of the prim.

<ParentID> - The local id of the root prim for this prim. If this is the root prim then this will be 0.

<GroupID> - The group that this belongs to. 0000000-0000-0000-0000-000000000000 if it belongs to no group.

<OwnerID> - The owner of the prim.

<LastOwnerID> - The previous owner of the prim.

<BaseMask> - Base permissions.

<OwnerMask> - Owner permissions.

<GroupMask> - Group permissions.

<EveryoneMask> - Everyone permissions.

<NextOwnerMasks> - Next owner permissions

<Flags> - The flags of this prim. Flags include None, Physics, CreateSelected, ObjectModify, ObjectCopy, ObjectAnyOwner, ObjectYouOwner, Scripted, Touch, ObjectMove, Money, Phantom, InventoryEmpty, JointHinge, JointP2P, JointLP2P, JointWheel, AllowInventoryDrop, ObjectTransfer, ObjectGroupOwned, ObjectYouOfficer, CameraDecoupled, AnimSource, CameraSource, CastShadows, DieAtEdge, ReturnAtEdge, Sandbox, Flying, ObjectOwnerModify, TemporaryOnRez, Temporary, ZlibCompressed. Multiple flags are comma separated (I think!).

<PayPrice0> - The payment price for this prim (what you see when you try to buy it).

'xml2' format

Here's the same object as above, but in 'XML2' format. As you can see, the format is identical except that there is no <RootPart> tag around the root part - it is assumed to be simply the first part instead.

<SceneObjectGroup>
  <SceneObjectPart xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <AllowedDrop>false</AllowedDrop>
    <CreatorID>
      <UUID>57956c4b-ff2e-4fc1-9995-613c6256cc98</UUID>
    </CreatorID>
    <FolderID>
      <UUID>b06d2e45-650e-4e5d-a08a-b03a6dd67bff</UUID>
    </FolderID>
    <InventorySerial>0</InventorySerial>
    <UUID>
      <UUID>b06d2e45-650e-4e5d-a08a-b03a6dd67bff</UUID>
    </UUID>
    <LocalId>2094307979</LocalId>
    <Name>Companion cube</Name>
    <Material>3</Material>
    <PassTouches>false</PassTouches>
    <RegionHandle>1099511628032000</RegionHandle>
    <ScriptAccessPin>0</ScriptAccessPin>
    <GroupPosition>
      <X>81.85081</X>
      <Y>157.5245</Y>
      <Z>21.32862</Z>
    </GroupPosition>
    <OffsetPosition>
      <X>0</X>
      <Y>0</Y>
      <Z>0</Z>
    </OffsetPosition>
    <RotationOffset>
      <X>0</X>
      <Y>0</Y>
      <Z>0</Z>
      <W>1</W>
    </RotationOffset>
    <Velocity>
      <X>0</X>
      <Y>0</Y>
      <Z>0</Z>
    </Velocity>
    <AngularVelocity>
      <X>0</X>
      <Y>0</Y>
      <Z>0</Z>
    </AngularVelocity>
    <Acceleration>
      <X>0</X>
      <Y>0</Y>
      <Z>0</Z>
    </Acceleration>
    <Description/>
    <Color>
      <R>0</R>
      <G>0</G>
      <B>0</B>
      <A>255</A>
    </Color>
    <Text/>
    <SitName/>
    <TouchName/>
    <LinkNum>0</LinkNum>
    <ClickAction>0</ClickAction>
    <Shape>
      <ProfileCurve>1</ProfileCurve>
      <TextureEntry>iVVnRyTLQ+2SC0fK7RVGXwAAAAAAAAAAgD8AAACAPwAAAAAAAAAAAAAAAAAAAA==</TextureEntry>
      <ExtraParams>AA==</ExtraParams>
      <PathBegin>0</PathBegin>
      <PathCurve>16</PathCurve>
      <PathEnd>0</PathEnd>
      <PathRadiusOffset>0</PathRadiusOffset>
      <PathRevolutions>0</PathRevolutions>
      <PathScaleX>100</PathScaleX>
      <PathScaleY>100</PathScaleY>
      <PathShearX>0</PathShearX>
      <PathShearY>0</PathShearY>
      <PathSkew>0</PathSkew>
      <PathTaperX>0</PathTaperX>
      <PathTaperY>0</PathTaperY>
      <PathTwist>0</PathTwist>
      <PathTwistBegin>0</PathTwistBegin>
      <PCode>9</PCode>
      <ProfileBegin>0</ProfileBegin>
      <ProfileEnd>0</ProfileEnd>
      <ProfileHollow>0</ProfileHollow>
      <State>0</State>
      <ProfileShape>Square</ProfileShape>
      <HollowShape>Same</HollowShape>
      <SculptTexture>
        <UUID>00000000-0000-0000-0000-000000000000</UUID>
      </SculptTexture>
      <SculptType>0</SculptType>
      <SculptData/>
      <FlexiSoftness>0</FlexiSoftness>
      <FlexiTension>0</FlexiTension>
      <FlexiDrag>0</FlexiDrag>
      <FlexiGravity>0</FlexiGravity>
      <FlexiWind>0</FlexiWind>
      <FlexiForceX>0</FlexiForceX>
      <FlexiForceY>0</FlexiForceY>
      <FlexiForceZ>0</FlexiForceZ>
      <LightColorR>0</LightColorR>
      <LightColorG>0</LightColorG>
      <LightColorB>0</LightColorB>
      <LightColorA>1</LightColorA>
      <LightRadius>0</LightRadius>
      <LightCutoff>0</LightCutoff>
      <LightFalloff>0</LightFalloff>
      <LightIntensity>1</LightIntensity>
      <FlexiEntry>false</FlexiEntry>
      <LightEntry>false</LightEntry>
      <SculptEntry>false</SculptEntry>
    </Shape>
    <Scale>
      <X>0.5</X>
      <Y>0.5</Y>
      <Z>0.5</Z>
    </Scale>
    <SitTargetOrientation>
      <X>0</X>
      <Y>0</Y>
      <Z>0</Z>
      <W>1</W>
    </SitTargetOrientation>
    <SitTargetPosition>
      <X>0</X>
      <Y>0</Y>
      <Z>0</Z>
    </SitTargetPosition>
    <SitTargetPositionLL>
      <X>0</X>
      <Y>0</Y>
      <Z>0</Z>
    </SitTargetPositionLL>
    <SitTargetOrientationLL>
      <X>0</X>
      <Y>0</Y>
      <Z>0</Z>
      <W>1</W>
    </SitTargetOrientationLL>
    <ParentID>0</ParentID>
    <CreationDate>1325896997</CreationDate>
    <Category>0</Category>
    <SalePrice>0</SalePrice>
    <ObjectSaleType>0</ObjectSaleType>
    <OwnershipCost>0</OwnershipCost>
    <GroupID>
      <UUID>00000000-0000-0000-0000-000000000000</UUID>
    </GroupID>
    <OwnerID>
      <UUID>57956c4b-ff2e-4fc1-9995-613c6256cc98</UUID>
    </OwnerID>
    <LastOwnerID>
      <UUID>57956c4b-ff2e-4fc1-9995-613c6256cc98</UUID>
    </LastOwnerID>
    <BaseMask>2147483647</BaseMask>
    <OwnerMask>2147483647</OwnerMask>
    <GroupMask>0</GroupMask>
    <EveryoneMask>0</EveryoneMask>
    <NextOwnerMask>2147483647</NextOwnerMask>
    <Flags>None</Flags>
    <CollisionSound>
      <UUID>00000000-0000-0000-0000-000000000000</UUID>
    </CollisionSound>
    <CollisionSoundVolume>0</CollisionSoundVolume>
    <TextureAnimation/>
    <ParticleSystem/>
    <PayPrice0>-2</PayPrice0>
    <PayPrice1>-2</PayPrice1>
    <PayPrice2>-2</PayPrice2>
    <PayPrice3>-2</PayPrice3>
    <PayPrice4>-2</PayPrice4>
  </SceneObjectPart>
  <OtherParts/>
  <GroupScriptStates>
    <!-- A large amount of scripting data comes here.  Please see later sections -->
  </GroupScriptStates>
</SceneObjectGroup>

Script states

If there are any scripts in any of the parts of the serialized object, that data will be included in the <GroupScriptStates> section at the end of the serialization. Each script will have it's own <SavedScriptState> entry. Here's an example.

...