Totem
This is a library built on top of HAPILib, intended to be used as part of HAPI.App.
It allows you to simply and quickly perform the necessary procedures to load, save, alter and view avatars, in the context of a logged-in user.
The library uses
jQuery Deferred to
handle asynchronous tasks, all of which return a promise
.
For full documentation, see the API docs.
Testing
Clone the Totem repo, then cd into its root and install dependencies:
npm install
When done, run
npm test
Setup
To begin using Totem, create a new Totem
object:
totem = new Totem endPoint: "https://my.hapi.instance-hapi", clientId: 2001
Note that this isn't necessary if you are using
HAPI.App, which will create a
Totem
object for you.
Quick Start
To get an inventory of assets for a logged-in user:
totem.inventory().then (inventory) ->
console.log inventory.get representation: "standard"
Once you have an inventory
object to work with, further calls to it are
mostly synchronous.
Representations
The representation: "standard"
option argument to inventory.get
is the Label of a HAPI
representation. You must always supply a representation, but you
may set a default one to avoid having to do so repeatedly.
You can set a default representation globally:
totem.config "representation", "standard"
Or only in the context of an inventory:
inventory.representation "standard"
Scoping
By default, Inventory.get
will return categorised arrays of assets with no
reference to which goods they might belong to:
category1:
[Assets ...]
category2:
[Assets ...]
You can get only assets belonging to a given good like so:
inventory.get representation: "standard", good: "default"
Again, you can set a default good in the context of an inventory:
inventory.good "default"
You can scope assets by category:
inventory.get representation: "standard", category: "category1"
This will return an array of assets in the given category.
Assets are always returned in the context of the given representation, so each asset in a returned array will look like this:
Id: 1
Label: "skinny_arm"
CategoryId: 1
GoodId: 1
DateCreated: "2012-10-17T19:20:36.97"
Layers: [...]
Metadata: ""
Thumbnail: ""
Categories and Goods
Retrieve a complete array of categories:
totem.categories().then (categories) ->
console.log categories
And a complete array of goods in the system:
totem.goods().then (goods) ->
console.log goods
Or just those available to the logged-in user:
totem.user().goods().then (goods) ->
console.log goods
Categories are always supplied in an array sorted correctly by the
SortOrder
property.
Avatars
To create a new avatar:
avatar = totem.avatar Label: "new-avatar"
Optionally, you can pass a hash of attributes to this method, which
will be applied to the created avatar (the most relevant of which will
probably be the Label
attribute).
To get a set of avatars already created by the user:
totem.avatars("standard").then (avatars) ->
console.log avatars
The argument to totem.avatars
is the name of a representation, which
is optional only if you have set a global default representation.
Equipping avatars
Once you have an avatar, you can equip it with a random set of assets:
totem.randomise(avatar, representation: "standard").then ->
console.log "Done!"
Or with an asset from the inventory:
assets = inventory.get representation: "standard", category: "arm"
avatar.equip "arm", assets[0]
Or with a defined set of assets (an 'ensemble'):
ensemble =
arm:
[Asset]
leg:
[Asset]
head:
[Asset]
avatar.build ensemble
Saving and displaying avatars
When you've made changes to an avatar, you can save it:
avatar.save().then ->
console.log "Done!"
And at any time, you can display it on a given canvas
element:
canvas = $("#myCanvas").get(0)
totem.drawOn avatar, canvas
Drawing an avatar on a canvas 'binds' it to that canvas; changing assets or colours on the avatar will automatically redraw it on the canvas.
Events
On an equip
, build
or colour[x]
call to an avatar, Totem will send the
avatarChange
event, which can be bound to like so:
$(totem).on "avatarChange", (event, data) ->
doSomethingWith data
Data is an object which will always have the property avatar
,
containing the avatar which sent the event, and event
, which is a
string representing the event type (build
, equip
, colour1
or
colour2
. If the event was prompted by an equip
or a local colour
change, there will also be a category
property giving the category
that the equip
was called on.