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&amp;name=Billiards&amp;domain=vastpark&amp;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&amp;name=NoClipPlugin&amp;domain=vastpark&amp;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&amp;name=HelloWorldPlugin&amp;domain=vastpark&amp;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>