|
Home | Developers | Help | Google Group | Contact Us
Table of Contents
Creating Your First Dimension
Gamaray can be used like a browser plug-in, in addition to being a stand alone app. When a URL is encountered that points to a document of MIME type "application/gamaray-gddf", the browser launches the Gamaray application which then loads the dimension.
Gamaray is also launched by the Android web browser when it encounters a URL with a scheme "gamaray://". For example "gamaray://www.yourserver.com/MyDimension.gddf" will open the dimension "MyDimension.gddf" located at "http//www.yourserver.com/MyDimension.gddf".
Start by creating a Dimension Description File (DDF) and name it something like "MyDimension.gddf". Place the file on your web server and create a link that points to this file on another web page. Make sure the link uses the "gamaray://" scheme. Below is an example DDF
You can simply change the longitude and latitude attributes and then deploy the DDF on your web server. When you open this file from your Android web browser it will launch the Gamaray application and display some miscellaneous objects around the coordinates you specified.
Dynamic Dimensions
The DDF file you create can be either dynamic (a CGI, Servlet, etc.) or static. Gamaray will send the longitude, latitude, and altitude of the device as POST parameters when it loads the DDF. If the DDF is dynamically created, it can use the parameters to limit the result set to objects near the user. Here is an example POST request sent by Gamaray to the DDF endpoint:
As with web applications, fairly complex interfaces can be created. The World 1.5 dimension, for example, uses only the features described on this page to create an application that lets people place and view objects in a shared persistent world. Here is a description of the POST parameters:
| event | The event that triggered this request to the server. Values can be "init", "refreshOntime", "refreshOnDistance", or "refreshOnPress" |
| eventSrc | Either "NULL", or for a refreshOnPress it is the id of the feature or overlay that was touched. |
| lat | The current latitude of the user. |
| lon | The current longitude of the user. |
| alt | The current altitude of the user. |
| bearing | The current bearing of the user. |
| pitch | The current pitch that the device is being held at. NOTE: This parameter is not always correct at the moment, but will be fixed soon. |
| width | The width of the device's screen. This is useful for laying out UI overlays. |
| height | The height of the device's screen. |
| uid | A unique id string that is randomly generated when the user installs the Gamaray application on their device. It shouldn't be used for true user identification, however it can be useful for storing preferences and similar information on the server. If the user uninstalls Gamaray, they will get a new id when they reinstall. |
| time | The time in milliseconds (the difference, measured in milliseconds, between the current time and midnight, January 1, 1970 UTC) |
We created a simple application to demonstrate some of the platform's features. Its a simple "game" in which you have to destroy all the Asteroids by touching them. Keep in mind the asteroids can also be above or below you. Click the Gamaray logo below from your G1 to try the game.
Asset Formats
3D Model formats: Currently Gamaray only supports a proprietary format called GAMA3D. We did this to cut down on file size and parsing time for the client application. We provide a simple web utility to convert from OBJ format to GAMA3D.
Image formats: Gamaray supports JPG and PNG images.
Coordinate System
The units in the 3D model files are interpreted as meters.
Refresh
A refresh can be triggered by elapsed time (see <refreshTime>), distance traveled (see <refreshDistance>), or when the user touches a feature or overlay that has an <onPress> tag with a refresh action. When a refresh is triggered, the Gamaray application simply calls the URL in the <refreshUrl> tag. If the event was triggered by a feature or overlay being touched, the id is passed in the "eventSrc" POST parameter. If your application would like to maintain a session state across refreshes, the <refreshUrl> can be encoded with the session id.
Actions
The <onPress> tag found in features and overlays can cause Gamaray to take these actions:
refresh: a refresh as decribed above will occur.
<onPress>refresh</onPress>
webpage: Gamaray will open the Android web browser and display the url.
<onPress>webpage: http://www.gamaray.com</onPress>
dimension: The dimension refrenced in the url will be loaded.
<onPress>dimension: http://www.yourserver.com/SomeDimension</onPress>
Schema
<dimension>
| Parent Tags: | NA |
| Child Tags: | relativeAltitude, refreshUrl, refreshTime, refreshDistance, locations, assets, features, overlays |
| Attributes: | version Set to "1.0" |
<relativeAltitude>
If "true", Gamaray will treat the <alt> tag in a <location> as being relative to the user's current altitude. This means if a feature has an altitude of 100m, it will appear 100m above the user whether he is standing at an altitude of 0m or 2000m. This can be useful if you are placing objects in a region where you don't know the elevation. If set to "false", then that feature at 100m would appear above the user if he is standing at 0m and way below if he is standing at 2000m. (Default = "false")
<refreshUrl>
When a refresh event is triggered, a new Dimension is loaded from this URL.
<refreshTime>
Tells the Gamaray to request a refresh after a certain amount of time has elapsed. If this tag is omitted, Gamaray will not refresh based on time elapsed.
| Parent Tags: | dimension |
| Child Tags: |
<validFor>
Time in milliseconds before a refresh is requested.
<waitForAssets>
When this tag is given a value of "true", Gamaray will wait until all assets have downloaded before the timer begins counting down to refresh. If "false", then the countdown begins as soon as the Dimension XML has been downloaded. (Default = "true")
|
<refreshDistance>
Tells the Gamaray application to request a refresh after the user travels a certain distance from the point where the last download of the Dimension took place. If this tag is omitted, Gamaray will not refresh based on distance.
| Parent Tags: | dimension |
| Child Tags: |
<validWithinRange>
Distance that the user must travel (in meters) before a refresh occurs.
|
<locations>
Contains a list of <location> tags, each with a unique "id" attribute.
| Parent Tags: | dimension |
| Child Tags: |
location |
<location>
A geographical point with a unique id.
| Parent Tags: | locations |
| Child Tags: |
<lat>Latitude
<lon>Longitude
<alt>Altitude in meters (also see <relativeAltitude>)
|
| Attributes | idMust be unique throughout the XML file. |
<assets>
Contains a list of <asset> tags, each with a unique "id" attribute.
| Parent Tags: | dimension |
| Child Tags: |
asset |
<asset>
Assets represent the content for a Dimension and are referred to by features and overlays. Multiple features and overlays can refer to the same asset.
| Parent Tags: | assets |
| Child Tags: |
<format>Allowed values are "PNG", "JPG", and "GAMA3D".
<url>The url for the content to be downloaded.
|
| Attributes | idMust be unique throughout the XML file. |
<features>
Contains a list of feature tags, each with a unique "id" attribute. There are 3 types of features: <feature3d>, <featureImg>, and <featureTxt>
| Parent Tags: | dimension |
| Child Tags: |
feature3d, featureImg, featureTxt |
<feature3d>
This tag places a 3D model at a geographical point. It also controls other attributes such as rotation and scale.
| Parent Tags: | features |
| Child Tags: |
<assetId>
The id of a 3D model asset.
<locationId>
Reference to a location from the <locations> list.
OR
<location>
An embedded location tag.
|
<onPress>
The action to take when the feature is touched by the user. If this tag is omitted, no action will occur when feature is touched. Note: pressing 3D features does not work great at the moment; you must press close to the center of the object to trigger the event.
<xRot>
Rotation around the X axis in degrees. (Default = "0")
<yRot>
Rotation around the Y axis in degrees. (Default = "0")
<zRot>
Rotation around the Z axis in degrees. (Default = "0")
<scale>
Scales the object equally on the x, y, and z axis by a factor. (Default = "1")
<xLoc>
Displaces the feature by a given number of meters along the x axis. (Default = "0")
<yLoc>
Displaces the feature by a given number of meters along the y axis. (Default = "0")
<zLoc>
Displaces the feature by a given number of meters along the z axis. (Default = "0")
<showInRadar>
If "true" the object will be visible on the radar, if "false" it will not. (Default = "true")
|
| Attributes | idMust be unique throughout the XML file. |
<featureImg>
This tag places an image at a geographical point. It's like a billboard, but it does not scale with distance and it always faces the user.
| Parent Tags: | features |
| Child Tags: |
<assetId>
The id of a JPG or PNG asset.
<locationId>
Reference to a location from the <locations> list.
OR
<location>
An embedded location tag.
|
<anchor>
Anchors a corner or other point on the image to the geo-point. Valid values are: "BR" (Bottom Right), "BC" (Bottom Center), "BL" (Bottom Left), "CR" (Center Right), "CC" (Center Center), "CL" (Center Left), "TR" (Top Right), "TC" (Top Center), "TL" (Top Left).
<onPress>
The action to take when the feature is touched by the user. If this tag is omitted, no action will occur when feature is touched.
<xLoc>
Displaces the feature by a given number of meters along the x axis. (Default = "0")
<yLoc>
Displaces the feature by a given number of meters along the y axis. (Default = "0")
<zLoc>
Displaces the feature by a given number of meters along the z axis. (Default = "0")
<showInRadar>
If "true" the object will be visible on the radar, if "false" it will not. (Default = "true")
|
| Attributes | idMust be unique throughout the XML file. |
<featureTxt>
This tag places a text box at a geographical point. It's like a billboard, but it does not scale with distance and it always faces the user.
| Parent Tags: | features |
| Child Tags: |
<text>
The text to be displayed.
<locationId>
Reference to a location from the <locations> list.
OR
<location>
An embedded location tag.
|
<anchor>
Anchors a corner or other point on the text box to the geo-point. Valid values are: "BR" (Bottom Right), "BC" (Bottom Center), "BL" (Bottom Left), "CR" (Center Right), "CC" (Center Center), "CL" (Center Left), "TR" (Top Right), "TC" (Top Center), "TL" (Top Left).
<onPress>
The action to take when the feature is touched by the user. If this tag is omitted, no action will occur when feature is touched.
<xLoc>
Displaces the feature by a given number of meters along the x axis. (Default = "0")
<yLoc>
Displaces the feature by a given number of meters along the y axis. (Default = "0")
<zLoc>
Displaces the feature by a given number of meters along the z axis. (Default = "0")
<showInRadar>
If "true" the object will be visible on the radar, if "false" it will not. (Default = "false")
|
| Attributes | idMust be unique throughout the XML file. |
<overlays>
Contains a list of overlays, each with a unique id. Overlays appear are 2D UI elements that appear in front of features, but behind the radar and alert messages. They can be used as decorations, buttons, or messages. There are 2 types of overlays <overlayImg>, and <overlayTxt>
| Parent Tags: | dimension |
| Child Tags: |
overlayImg, overlayTxt |
<overlayImg>
Places an image overlay on the screen.
| Parent Tags: | overlays |
| Child Tags: |
<assetId>
The id of a JPG or PNG asset.
<x>
The x location on the screen.
<y>
The y location on the screen.
<anchor>
Anchors a corner or other point on the image to the x/y point. Valid values are: "BR" (Bottom Right), "BC" (Bottom Center), "BL" (Bottom Left), "CR" (Center Right), "CC" (Center Center), "CL" (Center Left), "TR" (Top Right), "TC" (Top Center), "TL" (Top Left).
<onPress>
The action to take when the overlay is touched by the user. If this tag is omitted, no action will occur when overlay is touched.
|
| Attributes | idMust be unique throughout the XML file. |
<overlayTxt>
Places a text box overlay on the screen.
| Parent Tags: | overlays |
| Child Tags: |
<text>
The text to display.
<width>
The max width of the text box.
<x>
The x location on the screen.
<y>
The y location on the screen.
<anchor>
Anchors a corner or other point on the text box to the x/y point. Valid values are: "BR" (Bottom Right), "BC" (Bottom Center), "BL" (Bottom Left), "CR" (Center Right), "CC" (Center Center), "CL" (Center Left), "TR" (Top Right), "TC" (Top Center), "TL" (Top Left).
<onPress>
The action to take when the overlay is touched by the user. If this tag is omitted, no action will occur when overlay is touched.
|
| Attributes | idMust be unique throughout the XML file. |
Web site and all contents © Copyright Gamaray Ltd. 2009, All rights reserved.
| |
