Thursday, September 16, 2010

Beginner Tutorial Part 2

Now that we’ve got ourselves all set up to code, let’s begin! :)

 

Now as you all know, I’m also working on the C2toDS project, soCreature Labs Chocolate Vendor naturally, I’ve always got my eye on things I can convert from Creatures 2.  As I was browsing The Creatures of Avalon for interesting cobs, I came across this C2 Chocolate Vendor, credited to Creature Labs.

I knew then exactly what I wanted to do a tutorial on!  We’ll be remaking this vendor, from start to finish. :)  So let’s um…start!

First, grab the tutorial files here, and place them in your Tutorial 1 directory.  Also, place the sound file, “vndr” in the Creatures Sounds directory, and the sprite file, “moe_tutorial_chcd” in the Images directory of your Docking Station folder.

 

CAOS ToolOpen the CAOS Tool (which is highly recommended as it has syntax checking), or whatever program you’ll be using, AND start Docking Station.  Never try to develop and agent without having Creatures running!  A good developer beta tests constantly!

Also, start the Sprite Builder tool, and open up “moe_tutorial_chcd”.  Keep this open, we’ll be referring too it soon.

With the CAOS Tool open, make a new empty document.  The first thing we’re going to do is just write up the basic install and remove script for the vendor.

The script for creating this object is:

new: simp 2 23 9000 "moe_tutorial_chcd" 7 0 300

An explanation card of what each of these components “means” is below, a text version of this can also be found in your Beginner Document and the CAOS Documentation.  Here is a card explaining just what each value means (click for larger version).

The new: simp command is obvious as to it’s function, and if you look at Table 4 in your Beginner Reference Document, you’ll immediately see why the first two values are 2, and 23.  It tells the engine it’s a generic object, 2, known specifically as a vendor, which is 23.  Creatures’ brains interact with these classifiers and it’s how they know what an object is called and does.

But what about the 9000?  Well the 9000 is the Species Range.

All objects in the world have a Species. It helps the engine tell one object apart from another, since there could be more than one vendor in the world for example, each doing different things.  If it stopped at 2 23, how would the engine know that this is a Chocolate Vendor, and not the Justanut pod?

For this tutorial I’ve taken a portion of Creature Lab’s registered range, 0-10,000 and allocated 9000-9099 to tutorials. :)

Since this is our first vendor in the 9000-9099 range, we’ll be using 9000, but if it were our second vendor, we’d need to use 9001, so they don’t conflict.  Which means in a range from 9000-9099, you could have 100 vendors all doing different things!

In case you’re wondering, the Justanut pod is “2 23 5”. The Infinite Cheese Machine on the Shee Ark? That’s “2 23 1”.  See how they’re all different but still classified as a generic object (2), and vendor (23)?

The “2 23 9000”, as a whole, is called the “Classifier”. 

----- “moe_tutorial_chcd”

The second component of our first line of script is the name of the image file.  It’s pretty straight forward.  Whatever your sprite file is named, put quotes around it and type it out. :)  Our sprite file is named “moe_tutorial_chcd” so we’ve put quotes around it and…well there it is. That’s pretty much it… lol  Be sure to put quotes and don’t spell things wrong!

----- 7 0

The next two numbers are tricky and can give beginners a hard time. They tell the engine that this particular object is using 7 frames from it’s sprite file, and that it starts at frame 0.

But why 7?  Well if look up at the sprite file, you’ll see that the vendor has sprites from 0 to 6.  Frames 7 and 8 are the chocolate, so we don’t need those yet.  We want the engine to cut out frames 0 to 6, and keep those ready for when we animate the vendor.

But still, you may be wondering, why 7?  The last frame of the chocolate vendor seems to be 6, so why are we cutting out 7 frames?  Well, this can be confusing for beginners, but remember that we COUNT 0 as 1 frame.  Sure, it’s known as frame 0, but it’s still ONE frame and we need to count it. 

So we count, starting at 0, “0 1 2 3 4 5 6”. That’s seven numbers, 0 just happens to be the name of one of them.

Now we’re going to tell the engine what sprite to start at.  We want our vendor to start at the first frame, which is “named” 0.  That’s what the “0” is for in the “7 0”.

Advanced tip - The “0” is also known as the “Base” All frames are RELATIVE to this one. So if you told the engine to start at frame 4, that frame would be known as 0 to that agent.  It’s confusing at first, but you’ll see what I mean when we get to the chocolate.

----- 300

The 300 is the “plane”.  Ever notice how some objects are “in front of” or “behind” others?  This is how the engine knows where to put the object.  Usually you’ll want this to be around 500, but I did 300 for demonstration purposes.  When we inject the agent, you’ll notice it’s behind most other objects in the world, including creatures.

-----

On to the next line! :D

Now we want to tell the engine what properties our object has.  Is it heavy? Can it be clicked?  Does it fall under gravity or float? if it falls, how fast? Will it bounce? Slide?

new: simp 2 23 9000 "moe_tutorial_chcd" 7 0 300
bhvr 1

attr 198
elas 10
aero 5
accg 7
fric
50

I’ve written in a whole bunch of new commands, but don’t be overwhelmed, they’re self-explanatory, most of them. :)  We’ll start at the bottom first.

fric” tells the engine how much friction this object has on surfaces. A fric of 100 will make it completely immobile.  It won’t slide even on a 89 degree slope!  A fric of 0 will make it slide forever!  I’ve used 50 to make it slide a little, but stop fairly soon, and stay put on most angled floors.

accg” is the object’s “accelleration due to gravity”.  Basically, how fast does it fall?  I’ve used 7 because it’s a pretty heavy vender.

aero” is the objects air resistance.  Think of it like friction, but in the air. If you toss this object or it falls, how much is it going to slow down as it travels through the air?  That’s what aero defines.  I chose 5 arbitrarily.  It doesn’t really matter for our vendor cause it’s so heavy.

elas” is the object’s elasticity. How bouncy is it? Our vendor has an elasticity of 10.  It’s metallic and heavy, so it doesn’t bounce much.

Now we get to something a bit more complicated: attr.

attr” defines an object’s attributes. Can it be picked up?  Does it collide with walls? Respond to physics?  You can set the accg to 10, but if your attr isn’t set to obey physics, the object won’t fall. So how do you know what value to put here?

Well if you look at Table 1 in your Beginner Document or the Attribute Values in the CAOS Documentation, you can see what each number represents. 

We want our object to be carryable by the hand, activatable by the hand, suffer collisions, and suffer physics. And if you’re looking at the CAOS Documentation or your Beginner Reference you can see that each of those things has a value next too it. 

Mousable (which means it can be picked up by the mouse) is “2”, “Activatable” is “4”, Suffer Collisions is “64”, and "Suffer Physics is “128”.  So just add those together!  It’s that simple!

2 + 4 + 64 +128 = 198 – so our attribute value is 198. :)

The same thing is done for bhvr, which can be read “behavior” meaning “how can a creature interact with this object?” also known as “Creature Permissions”, except the values here mean different things. 

We only want our creature to be able to activate the vender, not eat it, hit it, pick it up, or anything else, so we’ll just use the number 1.

-----

Great, so our object is just about set up.  But where is it going to go, exactly?  Right now the engine makes the object, but it’s not put anywhere!  We need to tell the engine to move the object someplace.  We do this with the “mvto” command.

new: simp 2 23 9000 "moe_tutorial_chcd" 7 0 300
bhvr 1

attr 198
elas 10
aero 5
accg 7
fric
50
mvto 6100 9110

Ok great! The engine is moving our object somewhere, but where did the 6100 and 9110 come from?  Well if you go into Docking Station and press Shift+Ctrl+X on your keyboard, a tool will appear by your hand.  This tool tells you the X and Y values, or coordinates, the pointer is pointing at. 

Everything in the world is placed on this invisible pixel grid of X and Y values.

I moved around in the Comms Room till I found a good place beneath the agent injector and wrote down the values.  The 6100 is the “X” value.  Think of it as “left to right” on the screen.  The 9110 is the “Y” value.  Think of it as “top to bottom”.  Move around the world with this tool to get a feel for how it works.  You can choose to place the chocolate vender anywhere, I’ve just chosen to do so in the Comms Room.

Advanced Tip – If you get an error when trying to put the object someplace, try using mvsf instead of mvto.  It’s just like mvto, but moves the object to a “safe” location. Be aware however that mvsf is a Docking Station ONLY command.

Now our agent will be in the world, but how do we get it OUT of the world?  Now most developers do this LAST, but I like to do it first so I can test easily, and won’t clutter my world with hundreds of vendors!

rscr
enum 2 23 9000
    kill targ
next

rscr” tells the engine this is a “Remover Script”.

enum 2 23 9000” tells the engine to look at, or “target” every object with the classifier 2 23 9000. It actually means “enumerate over objects with this classifier”. Enumerate is just a fancy way of saying, “target them all one by one”.

kill targ” does just what it says.  It kills the target, which currently is every object with the classifier 2 23 9000, because if you recall, we just told the engine to target all those with the “enum” command.

next” basically just tells the engine to continue after targeting all the chocolate vendors with whatever comes next in the script.

-----

Ok, so our chocolate vendor is in the game, and it’s removable.

new: simp 2 23 9000 "moe_tutorial_chcd" 7 0 300
bhvr 1

attr 198
elas 10
aero 5
accg 7
fric
50
mvto 6100 9110

 

rscr
enum 2 23 9000
    kill targ
next

But, if you try and inject it now you’ll get an error, because we’ve told the engine that a creature can activate it, but we haven’t actually written in any activation script, so the engine is a bit miffed at us for not doing that!

Let’s ease it’s concerns and make our vendor functional by giving it an activation script.  To write a script we type this (before the rscr but after the mvto):

scrp 2 23 9000 1

scrp” tells the engine that this is a new script.  As you know, the 2 23 9000 is our chocolate vendor’s classifier.  So the engine knows that this script belongs to our chocolate vendor.

But what kind of script is it?  That’s what the last number is for.  If you look at “Script Types” in your Beginner Documentation or in the CAOS Documentation, you’ll see what each number represents.  We want this to be an “Activate 1” script, so we’ll make it 1.

Now the engine is going to add this script to the “Scriptorium”.  Basically it’s an imaginary repertoire of scripts that the engine uses and references when things are activated.

So, when your pointer or a creature goes to push the agent, this script is going to be dragged out of the Scriptorium and ran.  So!  Now we get to write in what happens!  Things are getting exciting! :D

First and foremost we want our vendor to animate.  You can see from the sprite file that we have seven frames of animation to run through. So let’s tell the engine to animate our vendor.

scrp 2 23 9000 1
lock
    frat 2
    anim [0 1 2 3 4 5]
    over

lock” locks the script.  I don’t want it being interrupted until it’s done. If you put a lock on a script, nothing can interrupt the script once it starts running. This will be necessary because our chocolate only gets vended AFTER the animation.  If it didn’t get locked, a norn could keep pressing the vendor forever, and the animation would keep resetting, but never finish, and thus, never vend any chocolate, and that would be sad. :(  So we’ve locked this script.  It can’t be interrupted until it finishes.

frat 2” tells the engine that any animations that follow need to have a frame rate of 2. You can think of it as the engine playing each frame twice, thus slowing down the animation by 1/2. A frat of 4 would slow it it down 4xs.

anim [0 1 2 3 4 5]” this is our animation sequence.  It says start at frame 0, and animate through frames 1 2 3 4 5.

over” tells the engine, don’t evaluate anything below this command until any animation currently playing finishes. So the engine will “wait” until the animation finishes.  That way the chocolate won’t come out until the chocolate vendor has reached frame 6 (where it actually looks like it’s coming out).

-----

Time to actually make chocolate! :D

This next section is going to be a bit confusing…so I’m going to put it in a brand new post. It’s going to include a lot of new concepts and some review, so that’ll make it all the more difficult.  Stay tuned.

No comments:

Post a Comment