totem

A library to easily manipulate avatar data in HAPI.

npm install totem
1 downloads in the last day
1 downloads in the last week
63 downloads in the last month

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.

npm loves you