Default Template: Beginner's Guide

From Docs.kaneva.com
Jump to: navigation, search

DT Logo.png

Welcome to the Kaneva for Developers Tutorial! Below we will help you quickly understand the basics of creating 3D games for Kaneva, as well as explain the features of the default template which you opened after installing Kaneva for Developers.

Use the table of contents below for quick navigation to specific sections of the tutorial. After following this tutorial, you'll soon be able to create your own 3D Apps!

If you're unfamiliar with 3D Apps, the FAQ can help answer newcomer's questions.

If you haven't already installed Kaneva for Developers, download the latest version here. For instructions on installing and setting up your own 3D App, read the Install Guide.

Contents

Overview - What is the Default Template?

The Default Template is intended to help new developers get started quickly with developing for Kaneva and assist experienced developers learn the details of elements like menus and 3D objects unique to Kaneva.

The Default Template includes a simple action game ("Coin Clicker"), along with pre-built menus with powerful features like leaderboards, premium item in-app purchases, friend requests, and more.

Through this guide, we hope to help you modify or remove our basic game logic, customize menus, create your own 3D game.

The included game, Coin Clicker, allows users to click the generated, spinning coin and increment their scoreScore.jpg, experienceExperience.jpg and game cash (a virtual currency)Game cash.jpg. These game mechanics can be re-used, modified, or discarded per your own game design goals.

Coin clicker.jpg

The menus included will help you manage your 3D App's social environment through the HUD at the top of this template. We have given you menus which manage:

DT HUD.jpg

Shop (Premium Items)
Sending Gifts
Badges
Leaderboard
Emotes
Friend Invites
HUD
Welcome
New Badge
Level Up
Winner


Change the look and feel

In case you didn't notice, the Default Template is rather bare on its own. If you're unfamiliar with customizing your App or Community's layout, a few helpful tools are linked below.

Again, if you haven't already looked it over, VanillaSmoothie's Hello World Tutorial is a nice starting point for editing your zone and attaching scripts to objects. The UI is outdated, but the Build Mode Basics are also a nice sidearm when customizing your App.

Texture the Ground

For starters, we'll simply throw a texture on the ground. The grid look probably isn't doing it for you.

  1. Enter Build Mode by clicking the "Build" icon on the bottom-right of your toolbar

Build mode icon.jpg

  1. Now open your Pattern menu by clicking the "Pattern" icon in the bottom-left of your toolbar, between "Rotate" and "Sounds"

Pattern icon.jpg

  1. By default, this menu will show your patterns you've uploaded yourself to the web. You can pick one of these if you wish. I'm going to change to the "Kaneva Patterns"

Pattern menu.jpg

  1. Select a pattern you like, click the floor and click "Apply"

Pattern applied.jpg

NOTE - Be sure you don't click the Default Template sign by accident. It's got a light effect on it, making it larger than it may appear

Texture the Sky

Applying a texture to the sky works exactly like the Ground.

  1. Enter Build Mode

Build mode icon.jpg

  1. Open your Patterns

Pattern icon.jpg

  1. Select a pattern you like
  2. Select the sky and click "Apply"

Sky pattern applied.jpg

Import a 3D Object

Importing your own 3D Object requires a bit more work than applying textures in your App, but fortunately we have this handy guide to help you through the process.

3D Objects Guide

More Design Help

The Designer Area is an extensive resource for help with animated objects, emotes, avatar clothing and more.

Here are a handful of helpful free tools you can use to help you design

App Management Basics

Your Apps' basic information is all available on your Kaneva 3D App web profile. Below I will show you how to get to your Apps.

Navigate to your 3D App

Go to http://kaneva.com, login, and click "My 3D Apps" in the navigation bar near the top of the page.

My 3D Apps.jpg

This will pull up a list of your current 3D Apps. Click "Manage 3D App" for the App you just created.

Manage 3D Apps (2).jpg

Clicking "Game Information" will bring up your App's essential information - Name, Game Id, Description, Search Categories and Tags, Age Restrictions, Access Type and a Thumbnail Image. Be sure to fill in as much of these fields as possible so other users can find your App successfully and distinguish yourself from other Apps.

Game Information.jpg App thumbnail.jpg

Next Steps - Menus and Scripts

Now that you've changed the basic look and feel of your game, and set up your Game profile, we'll learn more about the menus which control the game flow.

Setting up your KanevaWebHelper

Before editing menus, we need to setup the KanevaWebHelper for your game. Customizing the web helper to your game is how all of the social functions of the app work.

Keep note of your Game Id, Consumer Secret and Consumer Key found above in the game profile instructions. To set up your KanevaWebHelper, you'll need these values. Most of the Default Template menus will need the KanevaWebHelper to access your online info such as Badges, your Leaderboard, and Friends.

Your template should have your KanevaWebHelper setup by default. To ensure it is setup properly, open the Scripts Browser from your Dev Toolbar, browse down to WebIDs.lua and click Edit.

DefaultTemplate ScriptBrowser WebIDs.jpg

The first line of this script should read:

   GAME_INFO = {GAME ID, "CONSUMER KEY", "CONSUMER SECRET"}

If your Game Id, Consumer Key and Consumer Secret aren't seen here, go ahead and type them in and save the file. These values are referenced in the coinClicker.lua at lines 87-110. This script should already be attached to the Default Template sign.

You actually setup your KanevaWebHelper at line 110 that reads:

setupWebHelper(gWebKey, gWebSecret, true, "prod")

Now your App is ready to access various items from your 3D App's online profile.

Change the Welcome Menu

Remember when you first started the default template, you were presented with a Default Template welcome screen? Your Welcome screen is actually a menu. To edit your menu, click the "Menus" button in your Developer Toolbar to bring up the Menu Browser.

Build me4.jpg Open menu3.jpg

Here you can really stretch your legs and get creative with what you want to do with your Welcome menu. If you're unfamiliar with menus, check our VanillaSmoothie's Menu Tutorial or the Advanced Menu Tutorial if you're feeling brave.

For now, I'll simply show you how to make your menu a Welcome image with a button that closes the menu.

Add a Texture to your Menu

NOTE: All textures in menus must be .TGA or .dds and should be in powers of 2 (32x32, 64x64, 128x128, etc)

First we'll create a new menu to overwrite the old Welcome menu:

  • Click "Menus" to open the Menu Browser
  • Click New Menu
  • Next to Filename: type "Welcome.xml" and
  • Next to Script: type "WelcomeMenuScript.lua"

Welcome xml4.jpg


Now we'll add a texture and attach it to the menu's backgroundDisplay

  • Click the Element list box and select "backgroundDisplay"

Welcome xml5.jpg

  • Click "Select Texture" to open the Texture Editor
  • Click Import in the top-right to import your favorite texture
  • Find and select your texture under the "Available Textures" list box
  • Input the texture's dimensions into the "Left, Top, Bottom and Right" fields until your image shows up in the preview box like you want
    • You can also click the "Show Full Texture" button
  • Click "OK"

Add a Button to your Menu

We'll need to be able to close the Welcome menu now at the push of a button.

  • Click "Add"
  • Double-Click "Button" to add a button control element

New button2.jpg

  • Make the button whatever size you want and place it where you want
  • Next to Name: type "close"
  • Add text to the button so users know what the button does

Button placement4.jpg

  • Click File
  • Double-click Save Menu: to save and overwrite your current Welcome menu

Make the "Close" button close the menu

To close the menu, you need to add a little code to your menu's script so it knows what to do when the "Close" button is clicked.

  • Click Edit next to your menu's Script

Edit MenuScript.jpg

!!DON'T PANIC!! - You will see a lot of pre-existing code for the Coin Clicker game included in the default template.

  • Scroll down to where it reads - "function Dialog_OnCreate(dialogHandle)"

Add kgp touch.jpg

  • Above this block of code, make a little space and add the following three lines:
   function close_OnButtonClicked(buttonHandle)
       Dialog_Destroy(gDialogHandle)
   end

Kgp touch added2.jpg

Menu Button Controls

For a list of all the buttons used in the Default Template menus and the control names we used while developing, check out the Default Template Menu Reference

Menu & script communication

Before moving on to the social components of your game, here's a brief overview of how the menus you edited above communicate with the rest of the Default Template.

The Default Template has messages being passed from the client(menus) to the server and back again. Below is a simple diagram of what files talk to what other files: UML4Kids2.jpg

Badges

Adding a Badge to your 3D App is as easy as changing your profile picture on kaneva.com. Follow the steps below to add Badges to your 3D App.

Create a Badge

Navigate to your App's web profile page (http://kaneva.com, login, My 3D Apps, Manage 3D App). We want to edit our Badges.

Your 3D App2.jpg

If you have no Badges already created, this screen should appear empty. Click "Add an Item" .

Add An Item2.jpg

This will open a menu at the bottom to add a Badge of your own. Fill in the "Badge Name" and "Description" field, assign your Badge a point value
  • NOTE - You only have 1,000 points to assign to Badges per App. Choose your Badge point values wisely.
Finally, upload an image for your Badge and click "Add"

Add Badge2.jpg

And tada! Your new Badge is added and ready to be included to your game.

Badge Added2.jpg

Earning a Badge

Now that we have our Badges setup, we'll look at how to earn them inside a 3D App. Inside your 3D App, Badges will be earned when the user accomplishes something. This can be anything from walking over an object, clicking an object, reaching a certain level, etc. The idea is to decide at what point in your App you want users to earn Badges and add one line of code at that point.

Currently, the Default Template dishes out Badges for:

  1. Your first visit to the App (Treasure Seeker) TreasureSeeker.jpg
  2. Picking up your first coin (Lucky) Lucky.jpg
  3. and picking up 5 coins (TakeItToTheBank) TakeItToTheBank.jpg

The code for earning Badges based on the coins picked (your score) is found inside the "score.lua" file. To understand what the code does, we'll need to briefly explain how we currently earn badges.

When a user earns a Badge, we do 3 things:

  1. Earn the Badge
  2. Save what Badge was earned
  3. Tell the HUD that a new Badge was earned

This is explained more in depth in the Advanced Wiki. For now however, we'll bypass the glamor and simply earn a Badge when a user reaches level 10.

  1. Create a Badge on kaneva.com New Badge DT2.jpg
  2. Open "WebIDs.lua" from the Script Browser
  3. Add your new Badge in the BADGES table with the following format - ("Badge name = Badge ID". Like so:
   BADGES = {Lucky = xxx, TakeItToTheBank = xxx, TreasureSeeker = xxx, MyNewBadge = 541}

NOTE - Your Badge name can have spaces when you create it on the web. Just be sure you put it in the code WITHOUT spaces, or you'll have errors. Don't worry, your Badge name will still have spaces in it.


  • Open "levelingExp.lua" from the Script Browser
  • Scroll down to line 85, or where it reads, "-- If the player is level 10, they have "won" "

LevelingExp block.jpg

  • Add the following line after "if (totalLevel == WIN_LEVEL) then":
   earnBadge(user, BADGES["MyNewBadge"], true, "I just won the Default Template!", "Kaneva://YOUR APP NAME")

Leveling Exp block added.jpg


You'll need to Publish your changes before other users will see these changes. Note that this example shows you how to add a Badge for reaching level 10. If you want to earn a Badge for other events, simply put the code:

   earnBadge(user, BADGE ID, true, "Grats on your new Badge!", "Kaneva://YOUR APP NAME")

wherever you want your users to earn a new Badge. For more detailed information on earning Badges, check out the documentation.

NOTE - Earning a Badge requires you to setup your KanevaWebHelper. The Default Template will already have this handled for you, but it should be noted that if you plan on earning Badges in other Apps, you will need to do this.

Premium Items

Adding a Premium Item is almost as easy as adding a badge. You just need to do a little more work so that the game knows what to do with the item.

Add the Item via Kaneva.com

The first thing you will have to do to add a new premium item is to add it on Kaneva.com. This is very similar to adding a badge, all you have to do is go to My 3D Apps -> Manage 3D App -> Premium Items. From there, click Add an Item.

AddPremium1.jpg

Next you'll need to put in the information for your new premium item. This includes the name of the item, a description, the price, and an image for the item. Make sure that the status box is set to public so that other people will be able to see the item too! Once you're satisfied with your item, click Add.

AddPremium2.png

You should now be able to see your premium item on the premium items page! There is one more step you need to take to make your item official. Kaneva has to approve all premium items before you can sell them to Kaneva members. You will be able to buy the premium items yourself (for 0 credits) before they are approved, but nobody else will be able to see them. For other users to see your premium items, you'll need to request approval for them by clicking the check boxes next to the items you want to have approved and then clicking the "Request Approval for Selected Items" link.

AddPremium3.jpg

You've now added your premium item via the web. It should now show up in the Default Template for you (but not anyone else until it is approved). However, you won't be able to do anything with the item until you tell the game scripts about it.

Add the Item in 3D

First we need to add the item in our WebIDs.lua so we can reference the new Premium Item elsewhere:

  1. Open "WebIDs.lua" from the Script Browser
  2. Add your new Premium Item to the PREMIUM_ITEMS with the following format: ("Premium Item Name = Item ID"). Like so:
   PREMIUM_ITEMS = {GameCash = 3626188, MetalDetector = 3626189, EpicBeard = 3626202}

NOTE - Be sure you spell your Premium item's name here without spaces. Don't worry. Your Premium Item will still be seen as you specified on kaneva.com.

Be sure to save these changes.

Next we need to edit our premiumInventory.lua to store the new ID of our Premium Item:

  1. Open "premiumInventory.lua" from the Script Browser
  2. Scroll down to line 13 where it reads, "-- references to our premium items GLIDs")
  3. Add the following line below "METAL_DETECTOR_GLID = PREMIUM_ITEMS["MetalDetector"]
   EPIC_BEARD_GLID = PREMIUM_ITEMS["EpicBeard"]

NOTE - We used the name as we spelled it in the first step, when we were editing WebIDs.lua, not how it was spelled on kaneva.com.

EPIC BEARD GLID.jpg

We also need to add a little bit more code farther down in premiumInventory.lua, so that we know what the item is when we purchase it. Scroll down to the purchasePremium function (line 95) After the if block for METAL_DETECTOR_GLID ends (line 111) we need to add the following code:

   if purchasedGLID == EPIC_BEARD_GLID then
       itemType = "EpicBeard"
   end

The function should now look like this

AddPremium4.png

If you want the premium item to be giftable (and you should!), you'll need to add one more change similar to the one above. In the sendGift function (line 123) after the line if(giftName == "MetalDetector")... (line 128) add the line:

if(giftName == "EpicBeard") then giftGlid = EPIC_BEARD_GLID end.

The code should now look like this:

AddPremium5.png

Congratulations! You have now added your premium item into the App!

Make Your Premium Item Do Something

The point of premium items is to change how users interact with your app. A premium item can do anything from let a user into a VIP Room in a club to give a player extra armor against goblin attacks. For this example, we'll step back away from our Epic Beard item to something that makes a little more sense. Currently the Metal Detector item provided by the App does nothing. We will change it to give the user two coins on each click instead of one.

In order to do this, we only need to edit the coinClicker.lua file. This change is fairly easy to do, and it will only require us to edit one function, the kgp_touch function that is called each time a coin is clicked. Since we already have the code for earning one coin, we can simply add a check for the metal detector item and copy the code for earning one coin into it. That way we earn a coin when we click one, then if we have a metal detector we earn another.

The check for the metal detector should look like this:

if (playerHasItem(user, "MetalDetector", 1) then
    -- Add 2nd coin here!
end

To add the second coin, we can simply copy the rewards from the first coin over into the check so that it looks like this.

if (playerHasItem(user, "MetalDetector", 1) then
    updateExp(user, 50) -- Add 50 exp to the player (levelingExp.lua)
    updateScore(user, 1) -- Add 1 point to the player (score.lua)
    updateCash(user, 1) -- Add 1 gameCash to the player (gameCash.lua)
    addToInventory(user, "Game Cash", 1) -- premiumInventory.lua
end

After that, the code should look like this:

AddPremium6.png

Add a Gift for your Players

Built into the Default Template is a way to give an item to players as a gift. Unlike premium items or other items in your 3d app, this item can be used by the players outside of your app in the World of Kaneva. Note that you can only give an item that you created and uploaded to shop.kaneva.com to your players, you cannot gift any item that you did not upload yourself.

For more on creating your own items and uploading them to shop.kaneva.com, check out the designer tutorials.

Once you have your own item uploaded to shop.kaneva.com, you can add it to the default template by changing just one number! The first thing you have to do is get that number. You can find it by going to the shop page for your item on shop.kaneva.com, it should look something like this:

GiftShopPage.png

The number you'll need to remember will be in the same place as the one highlighted in red above. (It's in the URL bar, at the end of the address).

You will now have to open up the levelingExp.lua script. Line 34 of this script will say "GIFT_ITEM_GLID = -1" You will need to change that -1 to the number from the shop page, then you just need to save and publish the script.

GiftCode.png

By default, this script gives the item to the user once they reach level 10.

Publish Your 3D App

Publishing your 3D App

Personal tools
World Of Kaneva
Builders