VastPark Developer SDK

Transcription

1 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

2 Publisher... 8 Creator... 8 Player... 8 VastPark Server... 8 Scripting... 9 Documentation... 9 Plug-ins... 9 Overview... 9 Blueprint Loading Runtime Exposed Plug-in API Authoring Requirements Installation Writing your first plug-in Examples HelloWorld... 13

3 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 multiuser 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.

4 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.

5 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.

6 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=" <Widget Name="Billiards" Source=" 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!

7 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 plugin 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

8 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 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.

9 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.

10 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=" <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.

11 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 Get the free version of Visual Studio 2008 from here: 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:

12 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: and reference the associated projects from the Common directory.

13 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=" <Plugin Name="NoClipPlugin" Source=" 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=" 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>