Categories
Basic Tutorials

Basic Coding 1: Exploding Barrels

NOTE: A keyboard and mouse is needed for these coding tutorials, so that you can access Advanced creation mode (by pressing the TAB key).

Coding enables you to add dynamic interactions to your game, and gives you more creative freedom to experiment and make something that really stands out.

This series of tutorials is all about getting to grips with coding in Crayta. If this is your first time with Crayta, you might want to visit the Basic Tutorials, which go over the basic user interface of Crayta and some of the terms we will be using in this tutorial. Otherwise, if you are ready to jump in, let’s get to it!

Preface

Your first experience with coding could be a daunting experience. That’s why this tutorial is aimed at people who have never tried coding before, or have very limited experience. This tutorial will cover:

  1. Adding scripts to game objects
  2. Triggering some code with player interaction
  3. Using code to manipulate the game world
  4. Creating reusable templates

To follow this tutorial, you will need access to a version of Crayta with keyboard and mouse peripherals.

Creating The Game

To start, create a new blank game, or revisit one you already have in Create mode. Call your game Exploding Barrels.

When you have the game open in Create mode press TAB to enter Advanced Editor mode. 

Advanced Editor mode.

Adding Entities

In your library, click on the Library dropdown and select Meshes

Meshes are 3D objects you can place in your scene. Select Barrel (Exploding) and place it in your world with a left click. You are going to make this Entity explode when the player’s character touches it.

Select Barrel (Exploding) from the Meshes menu.
And place one in your Game World.

Creative Control

Whilst this tutorial uses a barrel, you don’t have to. Get creative! Maybe your character is trying to avoid homework, or dodge exploding axes. What’s the story here? Think about your game theme and use something that adds an original and exciting edge to your game.

Placing an Entity in the Game World will bring up the Entity Editor window, displaying the Entity’s Properties.

In the Entity Editor window on the right you can see the properties of the barrel. You can change these values by clicking on them and entering new values, or in small increments by using the arrow keys. 

Tech Tip: Entities In Depth

When you place a Mesh in your game Crayta behaves like a factory, duplicating the Mesh and giving it attributes which are required for it to exist in your game, such as it’s position and rotation. In order to distinguish between the Mesh in the Library, and the Mesh in the game, a Mesh which has been placed in a game is called an Entity

In the case of the ExplodingBarrel the Mesh is ExplodingBarrel, and the Entity is the specific instance of ExplodingBarrel in the game world.

If we were to place a new ExplodingBarrel in our game we would have another Entity. Each Entity will have the same attributes, but can have different values for those attributes, i.e. all ExplodingBarrel Entities have position and rotation attributes, but they can hold different values for each Entity.

Click the pencil next to the Name property and change the name of your Entity to ExplodingBarrel.

Great! 

Tech Tip: Organisation

It’s good practice to name your Entities in the Game World because it makes it much easier to navigate and maintain as the world becomes more complex. 

Do it from the start. It may seem trivial with only one or two Entities, but as your game level grows it becomes more time consuming to go back and organise it, or fix errors that have occured due to poor organisation.

You are going to make the barrel explode when the player walks into the barrel. Firstly, press F5 to play your level. Walk your character into the ExplodingBarrel. What happens? Nothing? That’s because we haven’t told Crayta how to respond to the player running into the object, or even that it needs to pay attention. And that’s what we are going to cover in this tutorial.

Press F5 again to return to the Advanced Editor.

Adding A Script

Make sure that your ExplodingBarrel entity is selected by clicking on ExplodingBarrel in the Entity Explorer. Add a new script from the Entity Editor toolbar by clicking Entity -> Add -> Script -> New Script.

Select Entity > Add > Script > New Script

Name your script ExplosionScript and press OK.

You’ll see that the ExplosionScript gets its own section in the Inspector window when ExplodingBarrel is selected. 

Click the edit script button next to the ExplosionScript’s scriptName to open the code editor.

Click the pencil icon next to the Script name to open it for editing.

You should see the following:

local ExplosionScript = {}

-- Script properties are defined here
ExplosionScript.Properties = { 
  -- Example property -- {name = "health", type = "number", tooltip = "Current health", default = 100},
}

--This function is called on the server when this entity is created
function ExplosionScript:Init()
end

return ExplosionScript

Tech Tip: Code?

The Script above contains code.

Code is a set of instructions that we give the computer. We have to write it in a way that both computers and humans can understand it, which is why it seems like an alien language some of the time. Learning to read and write code is like learning any new language, and (with a bit of practice) we can become fluent in reading and writing these instructions.

Different applications (including games) use different programming languages. The programming language we use in Crayta is called Lua which is a scripting language widely used in the games industry.

Tech Tip: Comments

Sometimes code can be difficult to understand, which is why most programming languages include a way of writing comments within the code. A comment is a segment of code which is ignored by the application.

Comments are written by developers (like you!) in order to describe the code from a human perspective. This way, if we forget (or don’t know) what the code itself is doing we can read the comments which will hopefully explain it to us.

In Lua, a comment is specified with with 2 hyphens(“–“) at the start of the line of code. For example:

-- This is a comment because the line starts with two dashes

Replace all the code in the script with the following:

local ExplosionScript = {}

-- Script properties are defined here
ExplosionScript.Properties = { 
-- Example property --{name = "health", type = "number", tooltip = "Current health", default = 100},
}

--This function is called on the server when this entity is created
function ExplosionScript:Init()

end

function ExplosionScript:OnCollision()   
  self:GetEntity().visible = false    
  self:GetEntity().collisionEnabled = false
end

return ExplosionScript

Can you spot what has been added?

...
function ExplosionScript:OnCollision()   
  self:GetEntity().visible = false    
  self:GetEntity().collisionEnabled = false
end
...

We have added one small chunk of code towards the end of the script. Notice the last line is still return ExplosionScript. This will always need to be at the bottom of the script.

Let’s read through what we’ve added…

function ExplosionScript:OnCollision()    
  self:GetEntity().visible = false    
  self:GetEntity().collisionEnabled = false
end

Line 13 states that Crayta should only run the code on line 14 when the player touches the ExplodingBarrel (OnCollision). When the player touches ExplodingBarrel, Crayta will run through each line of code until it reaches the end on line 16.

Line 14 uses self:GetEntity() to get the entity that this script is attached to, in this case, the ExplodingBarrel. It then sets ExplodingBarrel’s visible property to false. You can perform the same action by checking the visible checkbox in the Property window. 

On line 15, we use self:GetEntity() to get the entity again but this time we set the collisionEnabled property to false. This means the player will be able to walk through the (now invisible) ExplodingBarrel.

Save your script (CTRL + S) and return to the Game screen by clicking on the Game tab.

Preview your game and try walking into your ExplodingBarrel. You should see it magically disappear. You should also be able to move freely about where it once stood. If so, give yourself a pat on the back. If it doesn’t, take another look at your code and see if there is anything different from the one supplied above.

Adding Effects

With your game scene window open, use the Library dropdown to select Effects and choose Fire Explosion Large. Left click to place it in your scene on the ExplodingBarrel. Take a look at the Entity Explorer

Select Fire Explosion Large from the Effects menu in the Library.
Add it to the barrel in your game.

If your Fire Explosion Large entity is not a child of ExplodingBarrel then use the World Tree to click and drag Fire Explosion Large onto ExplodingBarrel.

Tech Tip: Parents and Children

Crayta uses a hierarchy system to group things together. Any entity can have another entity as a child (and children can have their own children too). This is a great way of grouping things together, and keeping things neat and ordered in Crayta. 

If you aren’t sure where your entity is in the scene hierarchy take a look at your World Tree. Child entities are listed immediately after their parent, and are indented the next level in, like a sub-list.

Be careful: Moving and rotating things only works from the top down. Moving a parent will move its children, but moving a child will reposition it relative to the parent, it won’t move the parent too!

Use the property inspector to rename your explosion Effect to “Explosion” and preview your game (F5). You should see Explosion explode as soon as the game starts. That’s good, but it’s not quite right. We don’t want things just randomly exploding at the start of the game, so now is the time to return to the editor and fix that (F5 again to return).

Select your explosion and use the Entity Editor to uncheck “active”.

If you preview your game again you should see that Explosion no longer explodes at the start. This tells you that setting your explosion’s “active” checkbox to true makes it explode. You can confirm this by clicking the checkbox on and off, and watching Explosion explode in the editor.

To make the Explosion explode during gameplay we will need to use a script to set the Explosion’s “active” property to true. Fortunately this is easy to add to the ExplosionScript. Select your ExplodingBarrel and click the Code Edit button to open your ExplosionScript.

Using code to reference something that exists in the game means we need to add a new property to the Property Bag.

Tech Tip: Properties

A property is like a shoebox we fill with data. By storing data in these “shoeboxes”, we can use and change them whilst the game is running. We always aim to use a descriptive name for our property, so that we can remember what it is later on.

The list of properties in a script is called a Property Bag. One script can have many properties in the property bag, each one a reference to a different piece of data. Properties can contain numbers, words, true or false values, or even other objects that already exist in our game. 

Use the following code to add a new property with the name “explosionEffect” to the Property Bag in ExplosionScript:

ExplosionScript.Properties = {    
  { name = “explosionEffect”, type = “entity” }
}

ExplosionScript.Properties = { declares that our ExplosionScript has a Property Bag. The properties are listed between the brackets starting with the open parenthesis { at the end of line 3, and finishing with the closed parenthesis } on Line 5. 

Within the parentheses {} Line 4 is declaring a single Property in our Property Bag, named “explosionEffect”. It also states that the explosionEffect Property is of the type “entity”. This means Crayta is expecting us to set this to one of the entities in our game world (such as a Mesh Entity, Sound Entity or other Entity). We will use this property to store a reference to our Explosion Effect.

We use the explosionEffect Property in our script further down. Let’s look at lines 10 – 14…

function ExplosionScript:OnCollision()    
  self:GetEntity().visible = false    
  self:GetEntity().collisionEnabled = false    
  self.properties.explosionEffect.active = true
end

Line 10 states that when the player touches the barrel (OnCollision) Crayta should run the code on line 11.

Line 11 makes the mesh invisible by setting it’s visible property to false. 

Linking Properties

When we define a property in a Properties Bag we can then set its value in the Crayta editor. In the Entity Explorer, make sure you have your ExplodingProp selected and you should be able to see that our explosionEffect Property has appeared under our Script

Here you can see that explosionEffect (or explosionEf…) has appeared as a property in the ExplosionScript area in the Entity Editor (bottom right).

Use the dropdown menu next to the explosionEffect Property in the Entity Editor and select Explosion from the menu.

Select your Explosion Effect from the explosionEffect Property dropdown in the Entity Editor for the barrel.

Return to the game editor by clicking on the Game tab. Preview the game and test your code! Hopefully when you now run into your ExplodingBarrel you see a mighty explosion. Great! But does it feel like there is still something missing? It’s a bit quiet for an explosion…it’s missing sound!

Adding Sounds

Sounds are great for adding weight and depth to your game. Using a similar process, we can add sounds to our game world, and make the explosion go “KABOOM”.

Use the Library dropdown to select Sounds. Type the word “explosion” into the Filter box to show only the sounds which include the term “explosion” in the title.

You can filter the Sounds by typing in the Filter box.

You will see that there are a variety of explosion sounds to choose from. To preview a sound, click the preview button. Choose your desired explosion sound and add it to your Explosion entity by left clicking on the entity in the viewport.

Add the explosion Sound you selected to the explosion Effect in your Game World.

With the Sound Entity selected use the Entity Editor to rename the sound ExplosionSound. 

Use the Entity Explorer to make sure your ExplosionSound is a child of your Explosion (this means if we ever move our explosion our sound will stay with it). 

Name your sound ExplosionSound. It should be a child of your explosion Effect.

Tech Tip: Sounds On Location

Sounds are localised in Crayta, so the closer you are to the sound, the louder it is, the further away you are, the quieter the sound is. If a sound is too faint or you don’t know if its playing check the sound position (you can double-click on it in the Entity Explorer to zoom the camera straight there).

If you now preview the level you will find that the sound plays automatically at the start of the level (similar to our Explosion Effect). To stop this occurring, select the ExplosionSound and uncheck the “active” checkbox in the Entity Editor.

Uncheck the active checkbox for the Sound in the Entity Editor.

Playing Sounds

Open the ExplosionScript in the script editor by selecting your ExplodingProp and clicking on the Code Editor button next in the ExplosionScript Entity Editor.

Add a property named explosionSound to your ExplosionScript’s Property Bag. Don’t forget to add the comma on line 5. In Lua you need to separate each item in the Property Bag with a comma.

local ExplosionScript= {}

ExplosionScript.Properties = {    
  { name = “explosionEffect”, type = “entity” },    
  { name = “explosionSound”, type = “entity” }
}

In the OnCollision() function set the sound to active using code. 

function ExplosionScript:OnCollision()    
  self:GetEntity().visible = false    
  self:GetEntity().collisionEnabled = false
  self.properties.explosionEffect.active = true    
  self.properties.explosionSound.active = true
end

This will mean the sound plays. Similar to the explosion, the sound will play when we set the active property from false to true (try toggling the checkbox in the Editor).

Save your script and return to the game editor window. In the ExplodingBarrel’s Entity Editor use the dropdown selector to set the explosionSound Property to the ExplosionSound in your game. 

Your final script should look like this:

local ExplosionScript = {}

ExplosionScript.Properties = {
  { name = "explosionEffect", type = "entity" },
  { name = "explosionSound", type = "entity" }
}

function ExplosionScript:Init()
end

function ExplosionScript:OnCollision()
  self:GetEntity().visible = false
  self:GetEntity().collisionEnabled = false
  self.properties.explosionEffect.active = true
  self.properties.explosionSound.active = true
end

return ExplosionScript

And your game screen should look like this:

Notice that the two Properties in the Script have been set to the Explosion (Effect) and explosionSound respectively. These two Entities have their active checkbox unchecked.

Preview your game. Make sure your sound is turned on and go collect that Exploding Barrel: Kaboom!

Creating A Template

Now that you have made an explosive Mesh, you can turn it into a template to re-use it again and again. To do this, make sure you have selected the top-level entity of what you would like to make a template – in our case ExplodingBarrel is selected.

Select the Entity you want to turn into a Template.

In the Entity Editor click Template -> Create New Template.

Click Template > Create New Template…

I’ve called my Template ExplodingBarrel, but you can name yours something that’s appropriate for you.

Name your Template something memorable and distinct.

Now look over to the Library window and select Templates from the dropdown menu, You can see that you have three items, including our new ExplodingBarrel item.

On the left-side of the screen, the ExplodingBarrel has been added to the Templates section of the Library.

Select your exploding item and add it anywhere in your game world by left-clicking. I’ve created a somewhat difficult situation for my player…

Now you can add lots of exploding barrels!

Summary

Congratulations on completing the first tutorial on coding in Crayta. In this tutorial we covered:

  • Adding game objects
  • Adding scripts to game objects
  • Running code on collision events
  • Using code to affect our game world
  • How to create a template from a group of entities

Whilst it may seem small, with these basic tools we can create a multitude of scenarios. We can use these same tools and techniques to add unique and interesting actions to our game, and make something that people want to play over and over again!

Next Steps

Not done yet? Continue to the next tutorial to investigate triggers, or get creative with what you know already. Why not try:

  • Create a bank door that explodes when you touch it
  • Create a magical axe that disappears amidst a sparkly magical animation when you walk into it
  • Make a bell that rings when you jump on it

Want to keep going? Check out the next tutorial, which looks at Lua in a bit more depth and shows you how to use triggers to commence in-game events: Basic Coding 2: Variables and Datatypes.