Backlog

Hello world:

Let's dive right in and show you just how easy BYOND is to use.

Open Dream Maker.

Select File->New Environment...

Environment files are .dme files. They are the base unit of a project. They include all the separate code files of a project, and will for the most part be automatically generated and filled for you, so you don't have to worry about editing them. Eventually, you'll find that outside of the auto-generated regions of the file, they are just like DM files.

Your new project will include a new DM file and a DME file. Your DM file will contain some sample code. Don't worry about this sample code yet. We'll cover this at a later time.



That's what your DM file should look like. Let's just select it all and delete it. Press Ctrl+A, then press the delete key on your keyboard. DM's code editor tabs work just like any text editor, or any other Integrated Development Environment if you already have a head start in programming.

With our newfound fresh start, let's make the simplest program possible.

We're going to output a message when the user connects to your game.

What you are going to type:



Literally press the tab key on the keyboard for tabs. These help you clarify something called scope. We'll cover what that is later on, but you will need to follow these instructions pretty exactly.

What the code will look like in the editor:



Users of other programming languages might be relieved to know that DM is very flexible in how it can be written. You can use spaces instead of tabs, but I'm pretty sure that's breaking a commandment or three, and you can also use curly brackets to denote scope. Let's take a look at some of the variations:





For advanced users, use whatever formatting you prefer, but the gold standard, most common syntax is one that's easy to read and easy to write. That's why we'll be sticking to tabbed, whitespace delimited, or the first example.


Compile and run your code. Press Ctrl+K, or Build->Compile in the menu, and then press Ctrl+R, or Build-Run.

You will see a Dream Seeker instance open up, and you should see a nice "Hello DM!" in the big white box in the body of the window. Great job! You are now a DM programmer.

When you are done patting yourself on the back enthusiastically, be sure to close Dream Seeker before continuing on to the next section. We don't need any spare windows laying around, and if you include any resources in your project, you'll notice that your rsc will be locked, preventing compilation while Dream Seeker or Dream Daemon is running a copy of that game. This will be important to know later on when your projects become more complex.

Tick Tac Toe:

Let's create a simple first game to get you a little more familiar with DM.

We're going to create a simple single-player tic-tac-toe game doing nothing fancy.

First things first, we need some art. Luckily, BYOND provides a nifty text-mode, so we don't actually need to draw anything yet!



We're seeing some new stuff here now, so let's try to work out what's going on.

First, we're defining a property of world. Properties, if you remember are places you can store information. In the case of world, we're changing a property called turf. From here on we're going to call properties variables. Why? Because that's what DM chose to name properties!

world comes with quite a few variables built into it. One of them is turf. When you set the value of turf to a type path, that type of turf will be used as the default turf.

What are turfs exactly? Well they are tiles. BYOND is a tile-based game engine, and every single space in the world is a turf. Turfs are literally the ground beneath your feet! Turfs can't move. They can neither be created nor destroyed. They simply fill all of your maps. Turfs are places that things can be! They contain movables, notably /objs and /mobs. They also can be made to look super snazzy.

So let's go further down in the code:



Here, we have created three children of /turf. Their paths are: /turf/blank, /turf/nought, and /turf/cross.

Notice how we've given them all a different text variable? That's so we can tell them apart when viewing the game in text mode.

Next, we need to create a map file for our game of noughty crosses. Go to File->New... (or CTRL+N), and in the dialog box that pops up, select a map file (.dmm) in the type dropdown. Name it "board".

Now, of course, set it to a size of 3x3. The map won't look like anything until you swap the drawing mode to text mode. You can do this via options->Icon Type->Text. If you think it looks a bit smallish, you can also go to options->Zoom and increase the zoom size. This makes working with tiny maps bearable.

Your map should already be full of /turf/board objects. If it's not, you can manually paint them on by selecting the /turf/board type in the object panel at the left and painting them in place with the add or box tool.

Let's expand on /turf/board a bit to make the game interactive!



Now we're running into something new!

Click() is a hook that's called on any atom when a player clicks on that atom in their client with their mouse.

We're telling it to create a /turf/nought instance. But this is a format we haven't seen before. Well, () means invoke. In local scope, () is actually an operator that will invoke whatever is on the left of it. In this case, it's new/turf/nought. new is a keyword. It creates the type on the right of it. In this case, it's /turf/nought. So we're creating an instance of the /turf/nought class. But what's src doing in that invocation operator? Well, the invocation operator actually takes something called arguments. Arguments are sort of like variables that you can hand off to a proc that will allow it to serve a variety of different behaviors using the same code.

In this case, the atom/New() proc takes a single default argument, which is "loc". Or rather, where the atomic object will be created. Creating a new turf doesn't really create a new turf. Rather, it changes the current turf into a different kind of turf. Turfs are the only objects that behave this way in DM, so just remember you aren't really creating anything. Just changing. For all other types that you use the new keyword with, a whole new instance will be created entirely separate from the old one.

In this case, src is the turf that was clicked on, so we're creating a new /turf/nought at the turf/board that was clicked on.

Let's compile and give it a shot!

Uh oh. Something's wrong. There's a big ol' M at the bottom-left corner. What's that doing there? It's not on our map! Well, actually if you hover over it, you can see the name of the object in the status bar. It's YOU! Or rather, it's the mob your client is connected to. Remember in Hello DM, how we changed mob's Login() proc? Well the default action of the Login() proc is to put the newly created mob as close to the bottom-left of the map that it is able if it isn't already on the map at the time of connection.

Weird, right? Well, we don't want that mob on the map. Let's change Login().



Wait, we didn't do anything? Yeah we did. Run your world. See what happens. Hey now! The screen is black! Did we screw up by not writing anything?

Let's try again.



Now we're back to where we started! Well, the first time we messed with Login(), we did what's called overriding it. When you modify a proc on an object type, that body of what you wrote becomes what that proc does. What it did before will no longer happen. The map is black because the mob isn't on the map, so the client isn't looking at anything. In fact, it's looking at nothing. The client attempts to draw the area around the mob, and if the mob is on the map, there's no there there to look at. Neat, right?

So why did the second one fix it? Well, ..() is a language feature called the supercall. ".." means super, or "previous", and () is to call, or invoke. .. is a shortcut for the previous version of the proc you overrode. In other words, ..() is to make the old behavior happen.

Let's actually make Login() do what we want now, though.



We're seeing something new again. client. We've talked about clients. They are an object type that stores information about the player that is connected to the world. The mob is just sort of a skin that they wear that is actually somewhere in the world. It's a graphical representation that the client drives around. mobs have a variable called "client", which allows you to do something called "access" that mob's client instance.

x.y means access x's y.

Accessing is a way to navigate through the variables and procs of an object. client stores a reference to the player's client, so you are actually accessing a variable itself. eye is a variable property of the client. It stores the atom that the viewport centers on. Normally, it's set to the mob that the client is connected to, but you can change it to another object and the viewport will follow that object around instead of the mob.

locate() is a way to grab a turf from the map. In this case, we're feeding it coordinates from the bottom-left of the map. We're grabbing the second tile right, second tile up on the first z-layer. locate() will grab the specific turf instance at that location.

Lastly, the = operator is called the assignment operator. This sets the variable on the left to the thing on the right.

The next line is pretty similar. The client has a variable called perspective. This affects how the client is determining what is visible. The two main properties are MOB_PERSPECTIVE, which is the default. This means the client won't draw anything the mob can't see. And EYE_PERSPECTIVE, which means that the client will draw as though the object stored in client.eye was doing the seeing.

And since we didn't supercall in Login(), the mob never gets put on the map. Now compile and run. You'll notice that the board is empty! Start clicking! You should have some noughts showing up all over!


Now we need to make the game playable against an AI. We're going to set it up in such a way that the AI will move completely randomly every turn, and the player will always go first.


Let's plan out what we need to do:

1) We need to tell the player that they have moved immediately after clicking a board turf.

2) We need to have the ai pick an open board turf at random.

3) We need to create a cross at the turf.


We can do this quite easily by creating a global variable to store the open spaces. This variable has to store multiple items, though. How will we acheive this? With a list, of course! Lists are a built-in type that can store any number of any kind of value. Let's learn how to define a new global variable.



Defining a new global variable is pretty self explanatory. You use the var keyword to name the variable so you can use it elsewhere. Since everything is technically in global scope, class and local scopes can use global variables too. However, variables defined in class scope can't be used in global scope, and variables in local scope can't be used in class or global scope. Variables only exist after they have been declared!

Since var isn't tabbed into an object or a method, it's a global variable!

But what's this list/open bit? This is called typecasting. When you are declaring a variable, you can specify the type of thing it should store. You don't have to do this, as all variables in DM can store any value DM supports. But if you store a value typecast to a specific type, you can safely assume that variable has a value that has all the properties and methods of that type. At least, during compilation. If you don't typecast, trying to access a property of the data stored in that variable will cause the compiler to give you a nasty little runtime error.

var / [type] / [label]

The label part of the declaration is the name of the variable that you will use when reading from or writing to the variable.

In our case, we're declaring AND defining the variable by using an assignment operator to an initial value of list(). list() is short for new/list(). It simply creates a list object. In this case, it's empty.

Now, let's make sure this list gets filled up with empty spaces:



New() is new. It's actually not the same thing as new, but it's related. when you use the new keyword to create an object, the instance you created has the New() hook invoked on it. This allows you to define the behavior of objects when they are initially created, and do some neat dynamic setup of your game.

open += src is also something we haven't seen before. += is the "addition assignment operator". It allows you to add the thing on the right to the thing on the left. In the case of a list, it allows us to add any kind of a value as an additional element in the list. We're adding src, or the turf/board instance itself when its created to the global.open list in this case.

Now then, we also need a way to let the AI move when the player makes each of their moves.

Let's write that code:



You'll see something a little weird in Click(). It's usr. Usr is another built in label/variable for all procs. It's similar to src, but instead of being the object the proc was called on, it's the mob that initiated the last proc.

In this case, it's the mob that belongs to the client that clicked on the board turf.

We're calling .Moved() with an argument of src to tell the mob that they Moved, and that this turf was the place they moved. Notice how we're doing this AFTER we technically replace src with /turf/nought? Again, turfs are never destroyed. Even though the Click() proc is only defined on /turf/board, and now src has turned into /turf/nought, the currently executing invocation of /turf/board/Click() keeps running, only src is now typed /turf/nought and has all the properties of a /turf/nought, and none of the properties of /turf/board. You have to be careful about this, because the compiler isn't going to catch any errors this kind of a change can cause, and you'll get a real nasty runtime error, which are like compiler errors, only they don't stop you from compiling. The game keeps running even though it's failing to work right.

We also defined Moved() under mob. Notice the proc keyword? Well Moved() isn't built in. We're not overriding an existing proc like very other proc we've set up. This keyword is just like var when defining a new variable, only it's for procs. It denotes structure entirely new to the scope its used in. Just like vars, procs can be global and class scoped. local procs are not supported in DM.

You'll notice the -= operator being used on open. This is the "subtraction assignment operator" We're subtracting the turf passed to Moved() from the global open variable. Then we check a property of lists called len. This will tell you how many values are in the list. If we have any values left, that means there's at least one move left, so we let the computer take a move.

the if() statement is new. it's a block-level instruction. It separates code out into what are called branches. The if statement will only allow the code tabbed inside of it to run if the condition inside the brackets is true. In this case, open.len being anything but 0 or null (empty, no value) will be considered true, allowing the next instruction to be the first tabbed into the if statement. If the if statement evaluates false, all of the code in the if statement is ignored. It jumps to the bottom of the if statement, which in this case, is the end of the proc.

See that local variable declaration? var/turf/t = pick(open), again we're casting a variable named t to the type turf. This is a local variable, so it will not be accessible in a lower scope. Its value is the result of a proc called pick(). pick() takes a list argument and will grab one random value out of the list. Once we have that value, we take the turf the computer picked out of the open tiles list and then create a new /turf/cross at that location.

Give it a run. You'll have to keep track of when you win or lose yourself. That'll be our next project, is allowing the game to figure out who won.

All of the code from the above excercise: