Asset Formats

Revision as of 17:59, 3 March 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>
      <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/>
</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 OpenSim has their own unique id (UUID).

<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/>
</SceneObjectGroup>