VastPark Developer SDK
Last Updated: 27th April 2009
Contents Introduction ............................................................................................................................................ 3
Metaforik ................................................................................................................................................ 4
How does it work? .............................................................................................................................. 4
Write once, run everywhere ............................................................................................................... 4
Schema Documentation ...................................................................................................................... 4
Examples ............................................................................................................................................. 4
Outerspace.xml ............................................................................................................................... 4
Different quality mesh.xml ............................................................................................................. 4
IMML ....................................................................................................................................................... 5
What is Immersive Media? ................................................................................................................. 5
Why create a new specification? ........................................................................................................ 5
Conventions ........................................................................................................................................ 5
Coordinate System .......................................................................................................................... 5
Position ........................................................................................................................................... 5
Rotation........................................................................................................................................... 5
Size .................................................................................................................................................. 6
Triggers ............................................................................................................................................ 6
Element Ownership......................................................................................................................... 6
Document Elements ............................................................................................................................ 6
Network Context ................................................................................................................................. 7
Schema Documentation ...................................................................................................................... 7
Examples ............................................................................................................................................. 7
Triggers with conditionals.imml ...................................................................................................... 7
Chase camera and autotween timeline.imml ................................................................................. 7
Keyframe timeline.imml.................................................................................................................. 7
Custom textures.imml ..................................................................................................................... 7
Applications............................................................................................................................................. 8
Publisher ............................................................................................................................................. 8
Creator ................................................................................................................................................ 8
Player .................................................................................................................................................. 8
VastPark Server ................................................................................................................................... 8
Scripting .................................................................................................................................................. 9
Documentation ............................................................................................................................... 9
Plug-ins .................................................................................................................................................... 9
Overview ............................................................................................................................................. 9
Blueprint ....................................................................................................................................... 10
Loading .......................................................................................................................................... 10
Runtime ......................................................................................................................................... 10
Exposed Plug-in API ....................................................................................................................... 10
Authoring .......................................................................................................................................... 11
Requirements ................................................................................................................................ 11
Installation .................................................................................................................................... 11
Writing your first plug-in ............................................................................................................... 11
Examples ........................................................................................................................................... 13
HelloWorld .................................................................................................................................... 13
Introduction VastPark is an end-to-end solution dedicated to solving the needs of immersive media, including
virtual worlds, through simple open specifications and a complement of core software and services.
The aim of VastPark is to enable the growth of an eco-system of solutions based on VastPark and the
interoperability with other Immersive Web platform software such as OpenSim.
The open specifications used as the foundation of VastPark include Metaforik for content
distribution and discovery, and IMML for scene definition. Both specifications are XML-based with
schema validation.
On the application front: VastPark Server is used for optionally hosting IMML and managing multi-
user connectivity and real time updates; the Player is used for rendering the IMML; VastPark
Publisher is for importing media, uploading it to an online CDN (it only supports S3 for now); and
VastPark Creator is a “Dreamweaver”-style authoring tool that enables you to design immersive
spaces in both a WYSIWYG design view and an IMML code view that features auto-complete code
suggestion and validation.
Metaforik Metaforik is a specification for syndicating dynamic media across distribution channels and works by
splitting intellectual property into a concept which we call an “Item” and digital assets which are
used to render the concept on the screen. By abstracting content into a request for a concept,
references to assets are abstracted in such a way that the consuming application is given the ability
to choose which actual asset to retrieve for a given item.
How does it work? Each Metaforik concept consists of an Item and at least one corresponding Asset. Each Item contains
metadata related to the concept it represents, such as description, audience and content tags,
associated URI and information on the publisher. Within that Item, there is the ability to define
multiple Assets that can represent it in a number of different scenarios.
Supported scenarios include:
Device/Platform specific file formats
Performance optimisation, ie: low-poly and high-poly versions of the same model
User-specific versions of a particular asset, ie: low-quality preview version for certain
users and high-quality versions for others
Write once, run everywhere Because there aren’t hard links to actual assets, the ability to write once, run everywhere is very
much a possibility and shifts the responsibility for content availability towards the content publisher.
Schema Documentation Documentation on the Metaforik schema is available in the base SDK directory, under the
Documentation\Metaforik\ folder.
Examples Located in the base SDK directory, under the Examples\Metaforik\ folder are some example
Metaforik documents.
Outerspace.xml
A concept of outer space that consists of two available assets, one for PC which is a fictitious plug-in
that hooks into the Hubble telescope to beam live data back and the other a mobile phone version
that just returns the latest image.
Different quality mesh.xml
A concept of a Dog that consists of two different meshes (low quality, high quality) as well as an
alternative representation targeted at a radio.
IMML IMML stands for Immersive Media Markup Language and is the means of transportation and
definition of logic, interaction and state in VastPark.
What is Immersive Media? Immersive media is a term used to describe the use of traditional media in a more immersive
manner than the norm.
Why create a new specification? HTML and other existing specifications are good at dealing with text and 2D visualisation. Other
specifications such as Collada are good at describing a scene at the mesh level, but as of yet there
isn't a widely used, open specification designed to deal with the spatial display and interaction of
multiple forms of media. Also interchange formats are not suitable for real time situations and for
real time data streams.
IMML aims to be a lightweight, "lean and mean" specification that developers will be equally happy
to dive in and code with as they are HTML. IMML aims to be abstract enough that it can be used in
conjunction with multiple devices and clients that use proprietary and/or open formats to describe
media files. IMML is designed to be able to encapsulate real time updates to the current scene.
Finally, IMML is easily generated or controlled by other scripting languages and external services and
data feeds, making it highly suitable for use in a fast changing Immersive Web of the future.
Conventions The IMML specification includes support for a number of strongly typed content elements for
positioning in 3D space. Certain elements support nesting of other elements in a parent-child
relationship.
As IMML is an extension of XML 1.0, the same general principles apply to the text, in that it uses the
default encoding utf-8 and honours the 5 predefined entities: quot, amp, apos, lt, and gt.
Coordinate System
IMML uses a three dimensional Cartesian coordinate system, under the left-hand rule where the x-
axis increases to the right, y-axis increases upwards and the z-axis increases away from the origin.
All coordinates are with respect to the parent element. The outermost parent element is the world
which follows the rules defined in the above diagram. All elements placed as the child of the world
are referred to as being elements in world coordinates.
Position
Position is defined as a Vector3, expressed in metres. Position is always relative to the parent
element and has a precision to the limit of a floating point number. An undefined position will
default to the origin of the parent element.
Rotation
Rotation is defined as a Vector3, expressed in radians. Rotation is always relative to the parent
element and has a precision to the limit of a floating point number. An undefined position will
default to a rotation of 0,0,0 relative to the parent element.
Size
Size is defined as a Vector3, expressed in metres. Size has no relationship to the parent element and
maintains a precision to the limit of a floating point number.
Triggers
All triggers follow a specific timing as when they can execute and what can trigger them.
Loaded
Fires when all child elements of the element’s context have completed loading.
NetworkConnectionEstablished
Fires when a network connection has been established. Cannot fire until after the document context
has fired the Loaded event
Element Ownership
All IMML elements have the ability to be network active. An IMML element is considered network
active when it contains a Network element with the enabled property set to true.
Document Elements IMML allows for two different document elements, the base IMML container element and a slightly
more lightweight Widget container element. The main difference being that the Widget container is
intended for re-usable components which can be referenced within the context of the IMML
container scope.
For example, the following mark-up references a Widget that represents a billiard table:
<IMML xmlns="http://schemas.vastpark.com/2007/imml/">
<Widget Name="Billiards"
Source="http://content.vastpark.com/VastParkWS/get.vpws?publisher=craigomat
ic&name=Billiards&domain=vastpark&context=park"
Position="0,1,8" />
</IMML>
The result of loading the mark-up is a billiard table complete with physics enabled balls and the logic
to watch for click events!
Network Context In a multi-nodal network context, IMML elements that are network enabled must report state
changes to all relevant nodes (clients/peers/servers/listeners).
In the scenario where an interested party joins after state modifications have occurred, that party
must be updated with the full state for each network enabled element.
Schema Documentation Documentation on the IMML schema is available in the base SDK directory, under the
Documentation/IMML/ folder.
Examples Some example IMML documents are included in the base SDK directory under the Examples\IMML\
folder.
Triggers with conditionals.imml
Contains some Primitive elements and one Collided Trigger with conditional logic governing its
execution. When executed, the Trigger writes a line to the console with the name of the element
the collision has occurred with.
Chase camera and autotween timeline.imml
Shows chase camera functionality along with an auto-tweening timeline that modifies the positions
of the chase targets.
Keyframe timeline.imml
Contains a timeline which keyframes a box Primitive’s position, rotation and size. Has a no-clip plug-
in for convenience to move around the space.
Custom textures.imml
Contains primitives arranged in such a way to reproduce an image from the homepage at
www.vastpark.com.
Applications VastPark currently consists of 4 main applications, each with a specific purpose. Currently these
applications require Windows XP SP2 or above with .NET Framework 3.5 SP1 (.NET Framework 3.0
for VastPark Server).
Publisher Used to import media into VastPark along with the creation of searchable metadata to make
your content discoverable to the types of users you want it to be. A publisher account is
required to login and can be requested via the contact form on www.vastpark.com.
Supported media formats: .x, .mp3, .ogg, .png, .dds, .jpg, .tga
Creator WYSIWYG editor for visually designing IMML documents that also provides an IMML editor
with auto complete and schema documentation on hover of element/attribute. Hooks into
the VastPark web service to discover content available for use by the logged in user.
The Creator provides runtime error/warning/message output for IMML and scripts, as well
as the ability to test script logic live during runtime.
Figure 1: IMML Console
Player The Player is an end user application able to play back a variety of different forms of media.
It supports IMML, PortableIMML, and Continuum through an extensible document provider
model. The source for a given document is able to be viewed, so avoid sensitive information
in the client version of your IMML documents.
VastPark Server The server is a multi-document hosting application capable of managing multi-user
interactivity and state data. Each hosted context is split into client and server IMML, with
client IMML being delivered to the client and server IMML remaining at the server for
server-side operations.
Scripting Scripting in VastPark is currently available via the LUA scripting language with some extensions for
performing specific tasks. Scripts are executed via invocation of a trigger, a timeline execute event or
manual requests.
Documentation
Please refer to the included VastScript API document located in the base SDK directory under the
Documentation\Scripting\ folder for further information.
Plug-ins
Overview Plug-ins in VastPark can be created using any .NET 3.0 (or lower) language that is part of the default
CLR.
They must implement IPluginComponent in the VastPark.Data namespace, which in turn requires
implementations for IUpdatable and IDisposable
Optionally, IParkObject can also be implemented by the plug-in which gives the plug-in access to the
various active engines for more granular manipulation of internal
operations.
Blueprint
Plug-ins require an accompanying XML document that determines which files need to be packaged
when publishing, which library contains the implementation of IPluginComponent and if the plug-in
code should be directly accessible via the scripting interface. The following is an example blueprint
and a description of each of the attributes:
<Plug-in Source="ExamplePlugin.dll" ScriptVisible="True"
Name="ExamplePlugin" xmlns="http://schemas.vastpark.com/2007/plug-in/">
<Dependency Source="ExamplePluginDependency1.dll" />
<Dependency Source="ExamplePluginDependency2.dll" />
</Plug-in>
See the plug-in documentation under Documentation\Plugins\ in the base SDK directory for further
information on the plug-in blueprint schema.
Loading
Once acquired, the following occurs in sequence to load the plug-in:
1. Unpack and load assemblies into secure AppDomain
2. Construct object that implements IPluginComponent
3. If implements IParkObject, an IParkEngine reference is passed to the plug-in
4. Parameters specified in IMML are set to the requested values on the plug-in object (see
Exposed Plug-in API)
5. Elements specified in IMML are passed to the AddElement() method
6. The plug-in Load() method is invoked
7. If the IMML specifies the plug-in should be enabled, the plug-in is activated by setting the
Enabled property to true
Runtime
For plug-ins that are enabled, each update cycle of VastPark will result in a call to the Update()
method of the plug-in. VastPark aims to perform 60 updates per second, but this value may reduce
depending on a number of factors including complexity of the scene and the hardware it is running
on.
Avoid doing too much heavy work inside the update method to prevent your plug-in from slowing
things down. Use separate threads for long running tasks, web requests that may have inconsistent
availability and other tasks that will likely take longer than 10ms to complete.
Exposed Plug-in API
The IMML specification allows for plug-ins to be customised at runtime, with all properties marked
as public able to be set via nested Parameter elements. The only limitation is that the properties
must be convertible to IMML types. IMML types include bool, double, float, int, string, RGB,
Timespan, Vector3 and a variety of others.
Authoring
Requirements
Before authoring a VastPark compatible plug-in, you must have a system which is capable of
compiling .NET Framework 3.0 source code. This means you must have a Windows PC running XP
SP2 or above and an IDE like Visual Studio 2008.
Get the free version of Visual Studio 2008 from here: http://www.microsoft.com/Express/
Installation
The SDK comes with a Visual Studio template for authoring plug-ins and a number of plug-in
examples. To make the plug-in template available to Visual Studio, copy VastParkPlug-in.zip to your
Visual Studio project templates folder.
Usually, this is located at
%userprofile%\Documents\Visual Studio 2008\Templates\Project Templates\
or
(%userprofile%\My Documents\Visual Studio 2008\Templates\Project Templates\ on Windows XP)
Verify it’s installed correctly by creating a new project in Visual Studio and looking under the My
Templates section. You should see VastParkPlugin in there.
Writing your first plug-in
Using the newly installed VastParkPlugin template, create a new project. Your solution should now
look something like this:
Fix the missing references by pointing to the included libraries inside the Libraries folder and you
should now have a buildable solution to begin adding your logic to.
Alternatively acquire the latest version of the source code from the public SVN repository at:
http://vastpark-svn.cvsdude.com/public/trunk and reference the associated projects from the
Common directory.
Examples Located in the base SDK directory, under the Examples\Plugins\ folder are some example plug-ins.
HelloWorld
This example sets two textures in an alternating fashion to the added elements. The time between
alternating the images can be adjusted by modifying the CycleTime property.
Example usage:
<IMML Name="MyPark" Camera="NoClipCamera" PhysicsSpeed="1" SoundSpeed="1"
AnimationSpeed="1" Gravity="0,-9.8,0" GlobalIllumination="#4c4c4c"
xmlns="http://schemas.vastpark.com/2007/imml/">
<Plugin Name="NoClipPlugin"
Source="http://content.vastpark.com/VastParkWS/get.vpws?publisher=craigomat
ic&name=NoClipPlugin&domain=vastpark&context=park"
Enabled="True">
<Element Name="NoClipCamera" />
</Plugin>
<Camera Name="NoClipCamera" Position="0,0.9,-2"/>
<Plugin Name="HelloWorld"
Source="http://content.vastpark.com/VastParkWS/get.vpws?publisher=craigomat
ic&name=HelloWorldPlugin&domain=vastpark&context=park"
Enabled="True">
<Element Name="Box"/>
<Element Name="Box1"/>
<Element Name="Box2"/>
<Element Name="Box3"/>
<Parameter Key="CycleTime" Value="5000"/> <!--Wait 5000ms between image
cycles-->
</Plugin>
<Light Type="Point" CastShadows="True" Diffuse="#4c4c4c"
Specular="#0000ff" />
<Primitive Name="Box" Type="Box" Position="-0.6,0,1"/>
<Primitive Name="Box1" Type="Box" Position="0.6,0,1"/>
<Primitive Name="Box2" Type="Box" Position="-0.6,1.1,1"/>
<Primitive Name="Box3" Type="Box" Position="0.6,1.1,1"/>
</IMML>