# IBIZA Avatar State Management
## Basics
The methods has to be called to the object "`AppController`" and the method names are provided below under each category. Each method will pass only one string parameter. Some methods require a direct string value while some methods require a json as a string.
## Callbacks (From Unity to Native)
Some methods sends callbacks to the native application. All the callbacks will be done through one method (from Unity) and has to be captured from the native side.
Callbacks are showed in respective methods
---
## 1. Change Current Scene
```csharp=
AppController.ChangeScene(string scenename)
```
Scene names are as follows
1. "```dashboard```" - main dashboard screen with parallax image
2. "```space```" - when the avatar want to be customized
3. "```store```" - when user need to buy new merch
4. "```myworld```" - open the myworld screen
5. "```levelup```" - Show Level up Screen only (no other animations)
6. "```cleandashboard```" - Dashboard without avatar, a bit darkned
---
## 2. Animate Avatar
```csharp=
AppController.AnimateAvatar(string animationname)
```
Animates the avatar. Following are the animations
1. "```wave```" - Waves at you
2. "```dance```" - Dances slowly
3. "```jump```" - jumps up
4. "```knock```" - knock the screen for a while
5. "```think```" - thinks for a while
6. "```showleft```" - shows left side with one hand
7. "```showlefttwo```" - shows left side with two hands
8. "```tail```" - wag the tail
9. "```clothcap```" - looks up at the cap
10. "```idle```" - moves to idle state and stays
---
## 3. Change Avatar Cloths
```csharp=
AppController.AttachCloth(string clothdatajson)
```
Avatar has the follwing cloth types
1) Head
2) Eye
3) Top
4) Bottom
5) Hands
6) Shoes
Calling the function to change cloths require the following data
1) Type (one from above) - string
2) Bundle URL - string
3) Asset name - string
4) Asset version - int
5) Equip Item - bool (If the item is equipped, send true)
Sample json to send (This should be convereted in to a string as a param)
```json=
{
"type" : "Head",
"url" : "https://url/bundlename",
"assetname" : "investigtor_hat",
"version" : 1
"equipped" : false
}
```
Bundles have to be different for iOS and Android
Following are some of the available cloth items (replace ios with android for android platform)
Use the name of the bundle as the asset name (eg: footballer_cap) and version 1 (it will be cached for the same version)
***NOTE ! - The following examples are for testing purposes only. The proper inks should be sent through the API***
#### Hat
1) https://storage.googleapis.com/arimac/ibiza_merch/ios/investigator_hat
2) https://storage.googleapis.com/arimac/ibiza_merch/ios/footballer_cap
#### Top
1) https://storage.googleapis.com/arimac/ibiza_merch/ios/investigator_top
2) https://storage.googleapis.com/arimac/ibiza_merch/ios/magic_top
3) https://storage.googleapis.com/arimac/ibiza_merch/ios/police_top
#### Bottom
1) https://storage.googleapis.com/arimac/ibiza_merch/ios/magic_bottom
2) https://storage.googleapis.com/arimac/ibiza_merch/ios/traveller_bottom
#### Sunglass
1) https://storage.googleapis.com/arimac/ibiza_merch/ios/footballer_sunglass
2) https://storage.googleapis.com/arimac/ibiza_merch/ios/investigator_sunglass
#### Hand
1) https://storage.googleapis.com/arimac/ibiza_merch/ios/magic_hand
#### Shoes
1) https://storage.googleapis.com/arimac/ibiza_merch/ios/footballer_shoes
More items will be added soon!
---
## 4. Change Avatar Level
The level of the avatar (The fitness and ears change) can be changed
Once changed, the avatar will preserve the chosen value
```csharp=
AppController.SetAvatarLevel(string avatarlevel)
```
avatarlevel should be a float that ranges between **0** and **100**
---
## 5. Set Avatar Configuration
```csharp=
AppController.SetAvatarConfiguration(string data)
```
The current merchandice state of the avatar has to be sent. Once this is set, the Unity will cache the values and will update only when this is called again.
You should call this API when logging in for the very first time or if you want to update the configuration of the avatar anytime.
Parameter should be a JSON string as follows
```json=
{
"level": 50,
"items": [{
"type": "Head",
"url": "https://url",
"assetname": "name",
"assetversion": 10
}, {
"type": "Eye",
"url": "https://url",
"assetname": "name",
"assetversion": 10
}, {
"type": "Top",
"url": "https://url",
"assetname": "name",
"assetversion": 10
}, {
"type": "Bottom",
"url": "https://url",
"assetname": "name",
"assetversion": 10
}, {
"type": "Hands",
"url": "https://url",
"assetname": "name",
"assetversion": 10
}, {
"type": "Shoes",
"url": "https://url",
"assetname": "name",
"assetversion": 10
}]
}
```
---
## 6. Reset Avatar Configuration
```csharp=
AppController.ResetAvatarConfiguration(string resetparams)
```
Once checked for new merchandise, user sometimes wanna keep the previous configuration. Since all the downloads are cached, it is not necessary to recall the above method to load all the files. Avatars state can be reset to the saved value with no issue.
Call this method when user goes back from the store if not the items are equipped.
`resetparams` - Send any message to log in unity
---
## 7. Generate a Snap shot
```csharp=
AppController.GenerateSnapshot(string reference)
```
Generates a snapshot of the current Unity scene and pass it as a base64 string binded with a json object.
Calling the function will generate the json object and pass it back to the native.
The passing object is as follows
```json=
{
reference:"test1",
image: "iVBORw0KGgoAA..."
}
```
`reference` = The Reference String you pass as a parameter
`image` = base64 convertion of the Snapshot
---
## 8. Change Theme
```csharp=
AppController.ChangeTheme(string theme)
```
Downloads and caches the theme images (Parallax Background)
The passing object is as follows
```json=
{
dashboardImages: {
imageUrls: [
"https://storage.googleapis.com/arimac/ibiza_merch/theme1/4.png",
"https://storage.googleapis.com/arimac/ibiza_merch/theme1/3.png",
"https://storage.googleapis.com/arimac/ibiza_merch/theme1/2.png",
"https://storage.googleapis.com/arimac/ibiza_merch/theme1/1.png"
]
}
}
```
`dashboardImages`, `imageUrls` = Array of links to the images in the parallax background
**NOTE** : Current implementation have 4 Image layers, the layers are put on top. Making the first image the furthest
---
## 9. Reset Default Theme
```csharp=
AppController.SetDefaultTheme(string reference)
```
Loads the default theme. Reference can be any string.
---
## 10. Show the Speech Bubble
```csharp=
AppController.SetSpeech(string data)
```
Shows the speech bubble by the side of the Avatar
The passsing object is as follows
```json=
{
language:"en",
text: "Hello there!",
time: 5
}
```
The parameters are
1. `language` - `"en"`, `"fr"`, `"ar"`
2. `text` - The text you want to pass through in any language (out ot three)
3. `time` - time to display the bubble. Best is 10 seconds
---
## 11. Hide the Speech Bubble
```csharp=
AppController.CloseSpeech(string reference)
```
If the speech bubble remains in the dashboard, the app can close the speech bubble calling this method. The reference can be any string.
---
## 12. Creating MyWorld
This is the most important part of the 3D engine. This method is used to create the path for the MyWorld based on the API responses received from the CMS.
```csharp=
AppController.GenerateMyWorld(string data)
```
The data object is as follows
```json=
{
interval:"daily",
bundles: [{
amount : 10,
type : "DEFAULT",
showTooltip : true,
bundleID : "1234",
stars : 0,
excludeSuperPlugins : ["super_power1", "super_power2"]
},{
amount : 20,
type : "DEFAULT",
showTooltip : true,
bundleID : "1235",
stars : 0,
excludeSuperPlugins : ["super_power1", "super_power2"]
},{
amount : 30,
type : "KEY",
showTooltip : true,
bundleID : "1236",
stars : 3
},{
amount : 40,
type : "DEFAULT",
showTooltip : true,
bundleID : "1237",
stars : 0,
excludeSuperPlugins : ["super_power1", "super_power2"]
}]
}
```
1. interval - `"daily"`, `"weekly"`, `"monthly"`
2. bundles - An array of the following
a. amount - the amount of the package (float)
b. type - `"DEFAULT"`, `KEY` (string)
c. showTooltip - Shows the amount next to bundle (bool)
d. bundleID - ID of the bundle
e. stars - Number of stars for the bundle (int)
f. excludeSuperPlugins : IDs of the super powers that need to be hidden when the certain bundle is selected
---
## 13. Selecting a Bundle
When the user scrolls the myworld, and tap on a bundle, the Avatar will jump on to that. At the same time, it will send a call to the native side with the respective bundle ID to populate the overlay UI (to show the jackpot etc.)
```json=
{
reference:"select_bundle",
id: "123"
}
```
1. reference - "select_bundle" will be a constant
2. id - ID of the bundle received when creating My World
---
## 14. Generating SuperPowers
When the MyWorld paths are generating, Super powers associated with them has to be created based on the interval (daily etc.)
```csharp=
AppController.GenerateSuperPowers(string data)
```
The data object is as follows
```json=
{
interval:"daily",
powers: [{
id : "1",
name : "Facebook Pack",
logoUrl : "https://api.ooredoo.dz/images/123.png",
price : 10.0,
},{
id : "2",
name : "Whatsapp Pack",
logoUrl : "https://api.ooredoo.dz/images/124.png",
price : 10.0,
},{
id : "3",
name : "Snapchat Pack",
logoUrl : "https://api.ooredoo.dz/images/125.png",
price : 10.0,
}]
}
```
1. interval - `"daily"`, `"weekly"`, `"monthly"`
2. powers - An array of the following
a. id - ID of the super power (should be unique)
b. name - Name of the super power
c. price - Price of the super power
d. logoUrl - url of the logo png image (string)
---
## 15. Selecting a SuperPower
Super power bundles are activated from Unity side. Once tapped, it will be hidden and will send the information to the native side. Based on the ID and the rest of the information, the Native UI can be populated.
The following is the data object that will be received to the Native end.
```json=
{
reference:"select_superpower",
superpower: {
id:"123",
name:"Facebook pack",
logoUrl:"https://api.ooredoo.dz/images/125.png",
price:20.0
}
}
```
1. reference - "select_superpower" will be a constant
2. id - ID of the superpower pack received when creating super power
3. name - name of the superpower
4. logoUrl - url of the logo
5. price - value as a float
---
## 16. Deselecting a Super Power
Once a super power is tapped, it will be invisible for the user. However, once the user deselect that power, it has to be visible again in the screen. For this, the native app should send a request to the Unity side to reappear it again.
```csharp=
AppController.AppearSuperPower(string id)
```
`id` = ID of the super Power
---
## 17. Showing the Level Up UI
Even if the scene change allows a level up UI, this is the preferred way to show the Level up UI
```csharp=
AppController.SetLevelUp(string data)
```
The data object is as follows
```json=
{
lang : "en",
xpfrom : 100,
xpto : 200,
levelfrom : 1,
levelto : 2
}
```
1. lang - Language (`"en"`, `"fr"`, `"ar"`)
2. xpfrom - XP before
3. xpto - XP now
4. levelfrom - level before
5. levelto - level to
---
## 18. Change MyWorld Path
Once my world is loaded, the following can be called to switch in between Daily, Monthly and Weekly
```csharp=
AppController.SetMyWorldPath(string interval)
```
interval - `"daily"`, `"weekly"`, `"monthly"`
---
## 19. Unity Scene Load Finish Message
Unity Scene takes a moment to load. Until it loads, Native app can use a placeholder (like a dummy blue screen with a spinner). Once Unity scene loads, it will send this message to Native side
```json=
{
reference : "unity_loaded"
}
```
---
## 20. Remove Avatar Cloths
This will remove the specifc cloth section for avatar. Good if you want to remove all the cloths.
```csharp=
AppController.RemoveCloth(string data)
```
Data Object is as follows
```json=
{
type : "Head"
}
```
Avatar has the follwing cloth types
1) Head
2) Eye
3) Top
4) Bottom
5) Hands
6) Shoes
---
## 21. Set Avatar Alignment
Works only in the dashboard and will take you to the dashboard. This will change the alignment of the avatar to left or right. Do not allow to run this command while a speech bubble is visible as it would make it wierd.
```csharp=
AppController.SetAvatarAlignment(string data)
```
data - `"LEFT"`, `"RIGHT"`
---
## 22. Unselect bundles
Will move the avatar away from the selected bundle
```csharp=
AppController.UnSelectBundle(string data)
```
data - `any random string`
---
## 23. Hide Super Powers
This will hide the selected super powers that pops up when avatar jumps from one to another. Call this function after a minor delay (Wait until avatar jumps to that place)
```csharp=
AppController.HideSuperPowers(string data)
```
Data object is as follows
```json=
{
interval: "weekly",
excludeSuperPlugins: ["super_power3", "super_power4", "super_power5"]
}
```
---
## 24. Hide Super Power
Hide only one super power
```csharp=
AppController.HideSuperPower(string id)
```
id - id of the super bundle
---
## 25. Change My World Theme
Loads the myworld theme based on the theme index. Calling this once is enough as it caches the theme index
```csharp=
AppController.ChangeMyWorldTheme(string index)
```
Index details are as follows
* 0 - Default Urban Theme
* 1 - Sports Theme
* TODO and more to come
---
## 26. Reset Default My World Theme
```csharp=
AppController.SetDefaultMyWorldTheme(string reference)
```
Loads the default My world theme. Reference can be any string.
---
# TODO - Pending
,
myWorldImages: {
imageUrls: [
"https://storage.googleapis.com/arimac/ibiza_merch/theme1/road1.jpg",
"https://storage.googleapis.com/arimac/ibiza_merch/theme1/road2.jpg",
"https://storage.googleapis.com/arimac/ibiza_merch/theme1/road3.jpg",
"https://storage.googleapis.com/arimac/ibiza_merch/theme1/road4.jpg"
]
}
`myWorldImages`, `imageUrls` = Array of links to the images in the Myworld components
Arrangement of the MyWorld roads has to be as follows. In any case the images are swapped (check the road design), the myworld buttons would not work properly
**NOTE - IMPORTANT** - Theme loading is a heavy process. So when you assign the theme once, this will cache it unless load default theme is called. Therefore please do not call load theme all the time when the screens get refreshed.
###### tags: `Ooredoo-Ibiza`
Sign in with Wallet
Connect another wallet