Your Game's Hootscript

  • Docs
  • Structure
  • Play
  • Build

The structure of your game

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.

Your game 'build'

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 Making Games and Distributing Them section under the Docs tab for more information.)

Playtest this build (Game will display below.)

Play your game

Welcome to Hoot!

Awesome Hoot Owl Logo

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 game that can be played in any ordinary Web browser.

You'll be writing your adventure game in a very simple language called Hootscript. You can see a randomly generated example Hootscript by clicking here (click again to make a new one!). Then play the generated example game by clicking the Play tab above.

Hootscript

What is Hootscript?

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.

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.

Things

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:

[this is a thing]:			

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!

Displaying Text

A text adventure game isn't much good without text. To display some text, simply put it between a pair of slashes like so:

/I am text that will display./

Your First Hootscript!

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:

[start]: /Hello world!/

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?

By the way, you can have as many bits of display text within a thing as you want. So this is totally fine:

[start]:
  /Hello /
  /my /
  /name /
  /is /
  /Mr. Hoot!/

Links

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:

/This is text with a link to a _thing_./ 

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:

[start]: /Hello _world_!/ 
[world]: /I am the entire planet!/

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.

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.

Variables (Storing Numbers)

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.

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.

set [apple count] to 2

To display a variable, simply include it in a piece of display text like so:

/I have [apple count] apples./

Let's give it a try with a really simple new Hootscript:

[start]:
set [number of sheep] to 8
/There are [number of sheep] sheep in the pasture./

Doing Things With Variables

You can manipulate variables by increasing or decreasing the numbers stored in them or setting them to new numbers. Here is an example:

[start]:
set [a] to 1
set [b] to 2
/A is [a] and B is [b]. /
increase [a]
decrease [b]
/(Now A is [a] and B is [b].) /
set [a] to 15
/(Now A is [a].)/

Making Decisions (if then else end)

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:

[start]:
set [the gate is locked] to 1
/There is a dark wooden gate in front of you. You can _try the handle_./

[try the handle]:
if [the gate is locked] equals 1 then
  /Sorry, the gate is locked.  You can _unlock it_./
else
  /The gate is unlocked, you can open it and go through./
end

[unlock it]:
set [the gate is locked] to 0
/You unlock the gate with the ancient brass key.  You can _try the handle_ again./

Try it now to see how it works! Not riveting gameplay, perhaps. But you get the idea.

You can have an if without an else, but not an else without an if. There are also other tests you can perform:

[start]:
set [a] to 4
if [a] equals 1 then /a is 1 / end
if [a] greater than 3 then /a is greater than 3 / end
if [a] less than 3 then /a is less than 3 / end
if [a] doesn't equal 3 then /a is not equal to 3 / end
if [a] equals [b] then /a equals b / end 

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.

Odds and Ends

To have a literal slash ('/') inside a string of text, you can escape it with a backslash like so:

[start]:/Have a good breakfast\/lunch, kids!/

To split up multiple paragraphs of display text, simply use a pair of underscores like so:

[start]:/First paragraph.__Second paragraph./

Hootscript is what we programmers refer to as "non-whitespace sensitive", meaning that you could also write the above as:

[start]:
	/First paragraph.
	__
	Second paragraph./

Speaking of sensitivity, Hootscript's things and variables are not case sensitive. That means that the following script will run just fine:

[start]: /You should _yell REALLY LOUDLY_!/

[yell really loudly]:
  set [Yell Volume] to 11
  /Aaaaaah!!! Yelling at volume [yeLL vOlUmE]!/

Which is a good thing, because sometimes you need to capitalize text, like when it's at the beginning of a sentence.

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:

[start]: /The [animal] is large./
[animal]: /elephant/ 

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:

[start]: /^[animal]s are large./
[animal]: /elephant/ 

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. :-)

Speaking of using things from other things, you can also explicitly run a thing with the run command like so:

[start]: /Pick the _red balloon_ or the _blue balloon_./
[red balloon]: /The red one reminds you of a song. / run [balloons]
[blue balloon]: /The blue one is clearly better. / run [balloons]
[balloons]: /You grab it and run into the forest with a squeal of delight!/

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):

[start]:
  set [bottle count] to 99
  /Let's _drink and sing_./


[drink and sing]:
  /^[count] bottle[s] of beer on the wall, [count] bottle[s] of beer. /
  if [bottle count] greater than 0 then
    decrease [bottle count]
    /Take one down and pass it around, [count] bottle[s] of beer on the wall.__/
    run [drink and sing]
  else
    /Go to the store and buy some more, 99 bottles of beer on the wall./
  end

[count]: if [bottle count] equals 0 then /no more/ else /[bottle count]/ end

[s]: if [bottle count] equals 1 then // else /s/ end		

Variables are global. This means that you can create a variable in one thing and test it and modify it in another thing.

Making Games and Distributing Them

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!

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.

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.

Once you're ready to share your game with others, follow these steps:

  1. Find the text editor for your system, not a word processor. Do a web search for "text editor" if you're not sure.
  2. Open this example game html file with your text editor. (You can save it from your web browser of you didn't download Hoot to your computer.)
  3. Click on the Build tab above. Copy the your game code.
  4. Replace everything between
    // --------------------------------------------------------------------
    // -------------------- Your game code goes below! --------------------
    and
    // -------------------- Your game code goes above! --------------------
    // --------------------------------------------------------------------
    with your game code.
  5. Save the HTML document and open it in your browser. There's your game!
  6. 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!
  7. Your game is now a single playable file, ready to be distributed and played by others!

About Hoot

This is version 1.5

Hoot is Copyright 2013 Dave Gauer. It is released free and open under the MIT License. Get the latest copy, view the source, or contribute at Bitbucket.