ID:1779979
 
Lesson #1 :: Get your face in the mud!

Lesson #1 | Lesson #2

Prologue


BYOND version 507.1248 introduced in 2014 the ability for game authors to write user interfaces in the languages of the web (JavaScript/HTML/CSS) or port existing BYOND 4.0 dmf skins to this new format. It's been a couple of months now but still there seems to be widespread confusion, a lack of decent reference and manual material, and quite simply a surplus of people not really understanding the extremely significant implications of being able to write your own client-end code. This series of "Webclient Lessons" will be focused on dispelling any misconceptions and providing a brief but informative introduction for building games with the HTML5 client.

Consider this tutorial series intermediate level, meaning I'm not going to be teaching you how to write BYOND code. If you want to learn more about BYOND's language, DM, then there are plenty of resources out there waiting for you. If you want to learn more about native dmf interfaces, Lummox Jr has written a fantastic introduction which I recommend readers to have read beforehand.

You will need some very basic knowledge of HTML and CSS to understand the bulk of this tutorial. I also highly recommend at least a brief course in JavaScript from W3 Schools or CodeAcademy. Your understanding of this tutorial is somewhat contingent on your understanding of JavaScript, but I'll try explain what I'm doing as I go along. Fret not! This first lesson will be void of JavaScript code.

We're going to have a slow start and probably not immediately get into juicy, hella fancy JavaScript UIs, but if you stick through, you might just learn something.

An Introduction


The Webclient (or Web Client, HTML5 Client) is essentially a lightweight wrapper that serves as an alternate client to DreamSeeker; the client program BYOND has been using now since the dawn of time. Assuming you have BYOND 507 or higher installed, Dream Daemon will have an option [+] to enable the webclient in your game. By default this will convert your .dmf file (or the default skin) into web form, allowing you to play most games out of the box.

Once you have a server up and running, you can access your game via the web by following this URL:

http://www.byond.com/play/[your_ip]:[port]


If you are hosting the machine locally, you may substitute your_ip for localhost or just 127.0.0.1. This lets you get around the need to forward your port. But what if you want people to be able to play your game on, say, your blog? You can do that too. You only need to include an iframe pointing to the URL above:

<iframe src="http://www.byond.com/play/embed/[your_ip]:[port]" width="640" height="480"></iframe>


If client.view or world.view are big enough to support it, you can increase the width and height of your iframe for a larger playing area. Keep in mind that if your users connect outside of the BYOND domain they may be subject to advertisements.

As you can see, getting your game up and running on the web is extremely easy to do and takes no time at all. But this is of course only scratching the surface of what the webclient has to offer. If your goal was simply to get your games running on the web, then the rest of the tutorial series definitely isn't for you. If you actually want to find out what's going on under the hood and build truly aesthetically-pleasing games and have ostensibly infinite control over the client-end, then read on! As I've said, we've only just begun.

"Hello Web!"


Now that we know how to host a basic project with the webclient, it's time we make a small game tailored specifically for HTML5.

We're starting as bare-bones as we can [+] for this project. But also keep in mind that we're not going to be using any .dmf files. For simplicity's sake, .dmf files are now the devil's army and have burned your women and pillaged your castle. You never want to see them again. Ever.

We'll start by making a new file, index.dms [+]. If you're familiar with apache or any other common web serving software, the concept of an index file should be very familiar to you. It's the front-end of our interface, and where we'll be dumping all of our controls at. Next, let's start to add some code to our new index file:

<body>
<div id="main" byondclass="child" skinparams="left=map;right=output;splitter=50;is-vert=true">
<div id="map" byondclass="map"></div>
<div id="output" byondclass="output"></div>
</div>
<div id="input" byondclass="input"></div>
</body>


Already things may seem to be becoming complicated, but I assure you if you've done any work with .dmf files, this is nothing new. The only difference is the information is now plaintext HTML as opposed to options in a visual editor. For instance, we know that a "child" class is a control that holds one or two panes with a splitter separating them. We know what a "map" is, and we certainly know what an "output" is. We can infer that the "child" element is being given the map and output panes to split.

The input element is the odd member out, isolated from the trio of linked UI elements.

Compile and run it, and you end up with something like this: [+].

Let's get a little more complicated before we wrap up this lesson. Let's set a few goals: we want to make the output element have a black background and a white foreground, but we want to do it using CSS. We also want to be able to press a button to say something! Let's start with the easiest, adding in a macro. We want to add the following code at the end of our index.dms file:

macro
T return "say"


Then the following verb:

mob/verb/say(t as text)
world << "[name]: [t]"


After running the game now, we can press the T button to call the say verb [+]. To add more macros, you can simply keep adding onto the macro list. Complex key combinations such as key+SHIFT and whatnot are also readily available for you to use. But now let's try to change the output css as per our previous goal. We want to add the following styling to our index file:

<style>
.byond_output {
background-color: #000; /* black background color */
color: #fff; /* white foreground color */
}

/*
Alternatively, you can use the selector #output. If you want to select a class, however, you always
have to prefix it with "byond_".
*/

</style>


The results are pretty swanky-looking [+]. You can get as creative with the styling as you want, which would otherwise be impossible with DreamSeeker. There are a myriad of different manuals out there for CSS and fancy CSS tricks if you want to add more pizazz to your text.


So you're still here, huh? Good on you! Not too hard, is it? Most of this might seem stupidly simple, and you might be impatiently waiting for the actual difficult JavaScript to spring up and scare you. You might be waiting for the moment you have to read dreaded JSON, miles and miles of embedded asynchronous lambda calls, and god forbid walls of jQuery.

All of this we'll go over in Lesson 2 and beyond. So stay tuned!
This lesson wouldn't be complete without linking the Webclient docs:

http://files.byondhome.com/LummoxJR/webclient_doc.html
Looking forward to lesson 2.
Nice introduction! Good idea on including a zip of the project files, that way if someone gets stuck they can always compare with a working version.

Ditto on looking forward to the next lesson.
Very good tutorial. I look forward to lesson 2!
Yup, this did the trick on helping me understand what I was missing so thanks for doing this Doohl. It's actually far simpler than I thought and maybe the dev guide should make it more explicit. As I re-read the dev, guide, it's there (.dms) but it didn't hit home until reading this tutorial.

Thanks.

I'm trying to do some testing to understand how the .dmf/.dms work together and I'm running into a "Internal Server Error" message in the browser (Chrome) when navigating to my locally hosted Dream Daemon session using 'localhost:8802'. Any ideas?
In response to PopLava
You have to use the byond play link, you can't connect directly:
http://www.byond.com/play/localhost:8802
or
http://www.byond.com/play/embed/localhost:8802

(to anyone else reading this, remember to replace "8802" with the port you're hosting on)
Ah ha. Thanks! Going to submit a feature request to get that LocalHost link added to the World startup output so we can just click on it.
In response to PopLava
PopLava wrote:
I'm trying to do some testing to understand how the .dmf/.dms work together and I'm running into a "Internal Server Error" message in the browser (Chrome) when navigating to my locally hosted Dream Daemon session using 'localhost:8802'. Any ideas?

There's a reason for this: Because your browser hasn't yet established itself as running the webclient, only a limited number of queries on your domain will work. Downloading cache files is not possible until then.