hoot/hoot.html

1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> 2 <html lang="en"> 3 <head> 4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 5 <title>Hoot - The Hypertext Adventure Game Builder</title> 6 7  8 <link rel="stylesheet" type="text/css" href="hoot.css"> 9 10 <script src="lib/jquery-1.7.1.min.js" type="text/javascript"></script> 11 <script src="js/hoot-grammar.js" type="text/javascript"></script> 12 <script src="js/hoot-parser.js" type="text/javascript"></script> 13 <script src="js/hoot-errors.js" type="text/javascript"></script> 14 <script src="js/hoot-prettystruct.js" type="text/javascript"></script> 15 <script src="js/hoot-examplescript.js" type="text/javascript"></script> 16 <script src="js/hoot-builder.js" type="text/javascript"></script> 17 <script src="js/hoot-compressor.js" type="text/javascript"></script> 18 <script src="js/hoot-runtime.js" type="text/javascript"></script> 19 20 </head> 21 <body> 22 23 <div id="layout"> 24 25 <div id="code-panel"> 26 <h1>Your Game's Hootscript</h1> 27 <textarea id="source">[start]: /Welcome to my game!/</textarea> 28 </div> 29 30 31 32 <div id="output-panel"> 33 <div class="tabs"> 34 <ul class="tablist"> 35 <li class="tab" id="tab_docs">Docs</li> 36 <li class="tab" id="tab_structure">Structure</li> 37 <li class="tab" id="tab_play">Play</li> 38 <li class="tab" id="tab_build">Build</li> 39 </ul> 40 </div> 41 42 <div class="css-blows">  43 44 <div id="structure" class="tabContent"> 45 <h2>The structure of your game</h2> 46 <div class="errorhell"></div> 47 <p>This display shows how Hoot sees your script. This may be helpful for understanding how statements are contained within things and how if/else structures work.</p> 48 <div id="structurearea"></div> 49 </div> 50 51 <div id="build" class="tabContent"> 52 <h2>Your game 'build'</h2> 53 <div class="errorhell"></div> 54 <p>When you're ready to distribute your finished game to others, your game is parsed and compressed into what is called a 'build', which will appear here. You'll be copying this code to create a game for distribution. Please see the <i>Making Games and Distributing Them</i> section under the Docs tab for more information.)</p> 55 <textarea id="buildarea"></textarea> 56 <a href="#" id="buildtest">Playtest this build (Game will display below.)</a> 57 </div> 58 59 <div id="play" class="tabContent"> 60 <h2>Play your game</h2> 61 <div class="errorhell"></div> 62 <div id="playarea"></div> 63 </div> 64 65 66 <div id="docs" class="tabContent"> 67 <h2>Welcome to Hoot!</h2> 68 69 <img src="hoot-logo.png" alt="Awesome Hoot Owl Logo"> 70 71 <p>Hoot stands for Hypertext Once upOn a Time. It's an adventure game creation tool. You write adventures in simple Hootscript and Hoot turns your script into a <a href="examplegame.html">game</a> that can be played in any ordinary Web browser.</p> 72 73 <p>You'll be writing your adventure game in a very simple language called Hootscript. You can see a randomly generated example Hootscript by <a id="generate-script" href="#">clicking here</a> (click again to make a new one!). Then play the generated example game by clicking the Play tab above.</p> 74 75 76 77 <h2>Hootscript</h2> 78 79 <h3>What is Hootscript?</h3> 80 81 <p>Hootscript is a programming language that has been designed specifically to create text adventure games. You can learn the basics in minutes. The following is both a tutorial and reference. By the time you've read everything in these instructions, you'll have made a game and put it into a simple file you can share with others.<p> 82 83 <p>Hootscript was designed for writing stories with lots of text. It may look a little strange in these short examples, but hopefully the syntax quickly makes sense as you begin to create real text adventures.</p> 84 85 86 87 <h3>Things</h3> 88 89 <p>Hoot games are made up of things. You make a thing by putting the name of the thing in square brackets followed by a colon like so:</p> 90 91 <pre class="snippet">[this is a thing]: </pre> 92 93 <p>Anything that comes after the colon is the stuff in the thing. [start] is a special thing because it is always the first thing that is run when the game begins. If you don't have a [start] thing, your game can't start!</p> 94 95 96 97 <h3>Displaying Text</h3> 98 99 <p>A text adventure game isn't much good without text. To display some text, simply put it between a pair of slashes like so: 100 101 <pre class="snippet">/I am text that will display./</pre> 102 103 104 105 <h3>Your First Hootscript!</h3> 106 107 <p>Now that you know about the [start] thing and displaying text, you're ready to create your first complete Hootscript. Delete all of the script to the right and then type the following:</p> 108 109 <pre>[start]: /Hello world!/</pre> 110 111 <p>Then click on the Play tab and you'll see your text. It's not much of a game, but it was certainly easy, right?</p> 112 113 <p>By the way, you can have as many bits of display text within a thing as you want. So this is totally fine:</p> 114 115 <pre>[start]: 116 /Hello / 117 /my / 118 /name / 119 /is / 120 /Mr. Hoot!/</pre> 121 122 123 124 125 <h3>Links</h3> 126 127 <p>A game needs interaction. You play a Hoot game by clicking on links. A link always points to a thing. To create a link, just type the name of a thing between a pair of underscores in a section of display text like so:</p> 128 129 <pre class="snippet">/This is text with a link to a _thing_./ </pre> 130 131 <p>Let's try making one now. We'll modify the [start] thing you've already created to include a link to a thing. Then we'll create the thing! Here it is:</p> 132 133 <pre>[start]: /Hello _world_!/ 134 [world]: /I am the entire planet!/</pre> 135 136 <p>From now on, when you see a code example like this, just remember that you can run it using the Play tab above. If you want to change your script and re-run it, just click on the Play tab again (even if it's already selected) and your game will be rebuilt and will start over at the beginning with your new script.</p> 137 138 <p>Now might also be a fun time to take a look at your little two line script with the Structure tab. Click on that to see how Hoot sees your Hootscript.</p> 139 140 141 142 <h3>Variables (Storing Numbers)</h3> 143 144 <p>Sometimes it's helpful to keep track of things in a game. For example, you could keep track of the number of times a person as taken an apple from a basket. Hootscript has variables for keeping track of numbers. It's very simple, but there's really no limit to what you can do by keeping track of numbers.</p> 145 146 <p>To store a number in a variable, you use the set command. In this example, the number 2 is being stored in a variable called "apple count". Variable names go in square brackets just like the names of things.</p> 147 148 <pre class="snippet">set [apple count] to 2</pre> 149 150 <p>To display a variable, simply include it in a piece of display text like so:</p> 151 152 <pre class="snippet">/I have [apple count] apples./</pre> 153 154 <p>Let's give it a try with a really simple new Hootscript:</p> 155 156 <pre>[start]: 157 set [number of sheep] to 8 158 /There are [number of sheep] sheep in the pasture./</pre> 159 160 161 162 <h3>Doing Things With Variables</h3> 163 164 <p>You can manipulate variables by increasing or decreasing the numbers stored in them or setting them to new numbers. Here is an example:</p> 165 166 <pre>[start]: 167 set [a] to 1 168 set [b] to 2 169 /A is [a] and B is [b]. / 170 increase [a] 171 decrease [b] 172 /(Now A is [a] and B is [b].) / 173 set [a] to 15 174 /(Now A is [a].)/</pre> 175 176 177 178 179 <h3>Making Decisions (if then else end)</h3> 180 181 <p>Finally, we get to the heart of adding logic to your game. Hootscript uses the traditional programming concept of an "if statement". It's very simple and is best explained with a brief playable example:</p> 182 183 <pre>[start]: 184 set [the gate is locked] to 1 185 /There is a dark wooden gate in front of you. You can _try the handle_./ 186 187 [try the handle]: 188 if [the gate is locked] equals 1 then 189 /Sorry, the gate is locked. You can _unlock it_./ 190 else 191 /The gate is unlocked, you can open it and go through./ 192 end 193 194 [unlock it]: 195 set [the gate is locked] to 0 196 /You unlock the gate with the ancient brass key. You can _try the handle_ again./ 197 </pre> 198 199 <p>Try it now to see how it works! Not riveting gameplay, perhaps. But you get the idea.<p> 200 201 <p>You can have an if without an else, but not an else without an if. There are also other tests you can perform:</p> 202 203 <pre>[start]: 204 set [a] to 4 205 if [a] equals 1 then /a is 1 / end 206 if [a] greater than 3 then /a is greater than 3 / end 207 if [a] less than 3 then /a is less than 3 / end 208 if [a] doesn't equal 3 then /a is not equal to 3 / end 209 if [a] equals [b] then /a equals b / end </pre> 210 211 212 <p>You now know more than enough to create an excellent adventure. Play around a little bit and try creating some simple stories and situations. If you wish to learn more, there are a few additional odds and ends you can use to improve your games below. Also below are instructions for creating a permenant and customizable copy of your games which you can easily distribute to other people to play.</p> 213 214 215 216 <h3>Odds and Ends</h3> 217 218 <p>To have a literal slash ('/') inside a string of text, you can escape it with a backslash like so: 219 220 <pre>[start]:/Have a good breakfast\/lunch, kids!/</pre> 221 222 <p>To split up multiple paragraphs of display text, simply use a pair of underscores like so:</p> 223 224 <pre>[start]:/First paragraph.__Second paragraph./</pre> 225 226 <p>Hootscript is what we programmers refer to as "non-whitespace sensitive", meaning that you could also write the above as:</pre> 227 228 <pre>[start]: 229 /First paragraph. 230 __ 231 Second paragraph./</pre> 232 233 <p>Speaking of sensitivity, Hootscript's things and variables are not case sensitive. That means that the following script will run just fine:</p> 234 235 <pre>[start]: /You should _yell REALLY LOUDLY_!/ 236 237 [yell really loudly]: 238 set [Yell Volume] to 11 239 /Aaaaaah!!! Yelling at volume [yeLL vOlUmE]!/</pre> 240 241 <p>Which is a good thing, because sometimes you need to capitalize text, like when it's at the beginning of a sentence.</p> 242 243 <p>Here's a neat trick: you can include a thing inside the display text of another thing. This is best explained with an example, so here's one - try it to see what it does:</p> 244 245 <pre>[start]: /The [animal] is large./ 246 [animal]: /elephant/ </pre> 247 248 <p>And remember how I mentioned needing to capitalize things at the beginning of a sentence? Well, you can do that with included things using the special ^ operator like this:</p> 249 250 <pre>[start]: /^[animal]s are large./ 251 [animal]: /elephant/ </pre> 252 253 <p>You can even display a thing inside itself! This is a form of what is called 'recursion'. Feel free to try it, but be warned: if you don't know how to do it properly you'll probably blow up your browser. :-)</p> 254 255 <p>Speaking of using things from other things, you can also explicitly run a thing with the run command like so:</p> 256 257 <pre>[start]: /Pick the _red balloon_ or the _blue balloon_./ 258 [red balloon]: /The red one reminds you of a song. / run [balloons] 259 [blue balloon]: /The blue one is clearly better. / run [balloons] 260 [balloons]: /You grab it and run into the forest with a squeal of delight!/</pre> 261 262 <p>Being able to run and display other things is an extremely powerful ability when combined with number variables. The only limit is your imagination. For example, here's the traditional 99 Bottles of Beer problem solved in Hootscript (uses recursion):</p> 263 264 <pre>[start]: 265 set [bottle count] to 99 266 /Let's _drink and sing_./ 267 268 269 [drink and sing]: 270 /^[count] bottle[s] of beer on the wall, [count] bottle[s] of beer. / 271 if [bottle count] greater than 0 then 272 decrease [bottle count] 273 /Take one down and pass it around, [count] bottle[s] of beer on the wall.__/ 274 run [drink and sing] 275 else 276 /Go to the store and buy some more, 99 bottles of beer on the wall./ 277 end 278 279 [count]: if [bottle count] equals 0 then /no more/ else /[bottle count]/ end 280 281 [s]: if [bottle count] equals 1 then // else /s/ end </pre> 282 283 <p>Variables are global. This means that you can create a variable in one thing and test it and modify it in another thing.</p> 284 285 286 <h3>Making Games and Distributing Them</h3> 287 288 <p>Before you start creating a real masterpiece, I highly recommend saving your game's Hootscript periodically in a text file. Don't trust all of your hard work to a browser - it will only end in tears!</p> 289 290 <p>Use a text editor, not a word processor (Microsoft Word, for example, saves text with "smart quotes" which may cause display issues with your game for some people). Notepad (Windows) and TextEdit (Mac) are fine. You'll probably wish to develop your game in a text editor and paste it into Hoot to run it. That way, your latest copy of the game script is always saved in a text file.</p> 291 292 <p>Start small! It's easy (especially when writing an adventure game with many paths) to start working on something big right away. There's nothing wrong with a big game. But you should try to build it a little bit at a time. Play through your game as you build it. This will help avoid bugs that are difficult to find. It will also force you to play through your game a lot - which is called 'play testing' and is very important for a quality game.</p> 293 294 <p>Once you're ready to share your game with others, follow these steps:</p> 295 296 <ol> 297 <li>Find the text editor for your system, not a word processor. Do a web search for "text editor" if you're not sure.</li> 298 <li>Open <a href="examplegame.html">this example game html</a> file with your text editor. (You can save it from your web browser of you didn't download Hoot to your computer.)</li> 299 <li>Click on the Build tab above. Copy the your game code.</li> 300 <li>Replace everything between <pre class="snippet">// -------------------------------------------------------------------- 301 // -------------------- Your game code goes below! --------------------</pre> 302 and 303 <pre class="snippet">// -------------------- Your game code goes above! -------------------- 304 // --------------------------------------------------------------------</pre> 305 with your game code.</li> 306 <li>Save the HTML document and open it in your browser. There's your game!</li> 307 <li>You can change the appearance of the game page by editing the CSS styles at the top of the document or any of the HTML. There are lots of great free tutorials out there which will teach you the basics!</li> 308 <li>Your game is now a single playable file, ready to be distributed and played by others!</li> 309 </ol> 310 311 312 313 <h3>About Hoot</h3> 314 315 <p>This is version 1.5</p> 316 317 <p>Hoot is Copyright 2013 <a href="http://ratfactor.com">Dave Gauer</a>. It is released free and open under the <a href="http://en.wikipedia.org/wiki/MIT_License">MIT License</a>. Get the latest copy, view the source, or contribute at <a href="http://ratfactor.com/repos/hoot/">ratfactor.com/repos/hoot</a>.</p> 318 319 </div>  320 321 </div>  322 323 </div>  324 </div>  325 326 </body> 327 </html>