What is the Adventuron CaveJam?

The Adventuron CaveJam is the first ever Adventuron (illustrated) text adventure game creation jam.

The jam involves adapting the provided source code (see bottom of this page) of a bare-bones text adventure, and adapting it into a better game.

NOTE: The original graphics should not be re-used, and new (pixel art style) graphics for all locations must be added. Bad graphics welcome, but try to use a fixed 8 or 16 bit style.

What is Adventuron?

Adventuron is a web-based text adventure authoring system.

The Classroom edition is available here:

https://adventuron.io/classroom

(editor not available on mobile browsers, but works fine of Chromebooks, laptops, desktops)

What is "The Cave of Magic"?

The cave of magic is a short game (by Chris Ainsley) that was designed to demonstrate features of the Adventuron system.

The original version (featuring bad graphics. and an updated "DX" version are linked below.

• The Cave of Magic (original)
• The Cave of Magic DX (featuring new graphics by Ricardo Oyón)

What Are Text Adventure Games?

A text adventure game is a type of game where a story or scenario is presented to the player in text
(+ optional graphics) and the player interacts with the world using keyboard, or voice, or any other method or inputting textual commands.

To learn how to play a text adventure play Excalibur ( https://adventuron.itch.io/excalibur )

Rules

• The game to be developed in the English language using Adventuron Classroom (desktop browser required for editor).
• Your remix of the game should involve 3 or more puzzles, the original puzzle may be removed or left in place.
• Games should be limited to VERB NOUN responses.
• The game must contain the forest, outside cave, the lake, and the treasure room locations. Location descriptions can be altered.
• The introduction text can be entirely removed / replaced.
• The win game condition is whatever you want it to be (in the original game it is entering the treasure room).
• Each location requires a graphic, even a bad graphic. Location graphics are suggested to be 128 x 40 pixels, or 256 x 80 pixels, or whatever resolution you prefer if not using pixel art style graphics. Pixel art style is strongly recommended for this jam but this style suggestion is optional.  The original graphic assets should not be used. The game requires a loading screen. The loading screen resolution is up to the author (256 x 192 is recommended if using pixel art style).
• A (optional) custom font may be used (see ZX Origins by Damien Guard - https://damieng.com/typography/zx-origins/ )
• The game should have nothing racist, sexist, or otherwise offensive in it. No curse words, or responses to curse words. Assume your game will be played by children.

Prizes

See the Prize Draw thread for more information on prizes (and full terms and conditions).  Prizes include a Raspberry Pi 4 2GB and more.

Qualifying entrants (that adhere to all the rules of the competition and of the jam) are automatically entered into the prize draw, but can opt out of receiving a prize by simply not replying, or by being disqualified by one of the rules.

Documentation

Multiple paths can be used to learn Adventuron.

It is suggested that you at least watch the first 10 minutes of the below video before doing anything else. If you have time, please watch the whole video, but if you are more confident, then you can see the full documentation for Adventuron below (section 10 is the quick start reference guide):

HTML Documentation

Click here see the full documentation for Adventuron Classroom (quick start guide is section 10).

Video Documentation

NOTE: The version of the game shown in the video lacks the new graphics, sound effects, and optional presentational elements.

How do I add my own graphics?

Adventuron's graphics editor is not ready yet, but https://lospec.com is quite a good online image editor.
Be sure to select either 128 x 40, or 256 x 80 for location graphics, and to choose the same palette for all images.

Support / Questions?

Follow @LearnAdventuron on Twitter, or use the Community button at the top of that page.

Additional Credits

Special Thanks to Ricardo Oyón for supplying the banner art for this gamejam, and the graphics for the "DX" version of "The Cave of Magic".

Source Code (copy / paste into Adventuron Classroom Editor)

NOTE: Graphics have been removed from the game and replaced with "placeholders". Use 'menu/import' function to import own graphics (should ideally be less than 16k per graphic)

// (1) Please watch the following video to 
//     demonstrate the editor features of Adventuron
//     ... https://www.youtube.com/watch?v=zbC_bSysbrA

// (2) To get rid of the tutorial side panel
//     Select MENU / Display Side Documentation

// USEFUL SHORTCUTS

// Click the header in Adevnturon Classroom to quickly
// navigate to different code sections
// Press Control + SPACE (or ALT + SPACE) to access code completion
//        ... see youtube video for demonstration of this feature.
// Press Control + F (to find code)
// Press Control + F x2 (to search and replace)
// Press Control + S to save the code and execute.
// Click Menu / Compile to export game as HTML.

######################################
# Code Start                         #
######################################

// Set the Start location to be lakeside

start_at                 = lakeside
start_theme              = my_theme

// Set the initial (or loading) screen to be
// the graphic asset with id 'loading_screen'

loading_screen           = loading_screen

######################################
# locations                          #
######################################

locations {
   forest       : location "You are on the forest path.\nTall <TREES<4>> tower over you on both sides." ;
   outside_cave : location "You are standing outside <THE CAVE OF MAGIC<5>>" ;
   inside_cave  : location "You are inside <THE CAVE OF MAGIC<5>>" ;
   lakeside     : location "You are by the side of a <BEAUTIFUL LAKE<2>>." ;
}

######################################
# connections                        #
######################################

connections {

   // The lakeside connects northwards to the foresat
   // So we can imply that forest connects southwards
   // to the lakeside.
   
   // When connecting locations, do not consider the blocks
   // between locations
   
   // Mazes are possible using north_oneway , south_oneway,
   // etc, but be careful not to frustrate the player.
   
   from, direction, to = [
      lakeside,     north, forest, 
      forest,       north, outside_cave, 
      outside_cave, north_oneway, inside_cave, 
   ]
}

######################################
# Objects / Scenery                  #
######################################

objects {
   troll          : scenery "an enormous troll" start_at = "outside_cave" ;
   sleeping_troll : scenery "an enormous troll (sleeping)" ;
   apple          : object  "an apple" ;
   treasure       : object  "a pile of treasure" start_at = "inside_cave" ;
}

######################################
# barriers                           #
######################################

barriers {

   // Blocks entry to the cave if the troll exists.
   
   block_cave : block {
      location               = inside_cave
      message                = THE TROLL IS GUARDING THE CAVE.
      block_when_exists      = troll
      show_blocked_exit      = true
   }
}

######################################
# on_startup                         #
######################################


// The on_startup hook runs at the start of the game, one time per game.

on_startup {

   // Print the graphic of the outside of the cave
   // This uses the png data of the graphic encoded
   // as text (at the bottom of this source code)
   : print_graphic "outside_cave" ;
   
   // ^c^ Tells adventuron to centre the paragraph horizontally.
   : print "^c^<- THE CAVE OF MAGIC DX -<12>>\n<A One Puzzle Game\nby Chris Ainsley<10>>" ;

   : beep millis = "100"  pitch = "0" ; // Pitch 0 = middle C.
   : beep millis = "100"  pitch = "2" ;
   : beep millis = "100"  pitch = "4" ;
   : beep millis = "100"  pitch = "6" ;
   
   // Waits for the player to press a button
   // click the mouse, or touch the screen.
   : press_any_key ; 
   
   : beep millis = "100"  pitch = "6" ;
   : beep millis = "100"  pitch = "4" ;
   : beep millis = "100"  pitch = "2" ;
   : beep millis = "100"  pitch = "0" ;
   
}

######################################
# on_command                         #
######################################


// The on_command block is used to handle player text input

on_command {

   // If the player types "examine trees" or "examine tree"
   // Then run the inner code. NOTE, adventuron automatically maps
   // examine to "look at" so if the player were to type
   // "look at tree" or "look at trees" it would also match
   
   : match "examine trees; examine tree"  {
      // If the player is located in the forest and has typed "look at tree"
      // or "look at trees" or "examine tree" or "examine trees"
      // then the game will print "Apple Trees".
      : if (is_at "forest") {
         : print "Apple trees." ;
      }
   }

    // If the player has typed "pick apple" or "get apple" then run the code inside this block
    // NOTE : Adventuron automatically associated verbs get with take, so this would
    //        automatically test for get apple, pick apple, or take apple.
    
   : match "pick apple;get apple"  {
   
      // The && characters represent an AND clause
      // is_at "forest" returns a TRUE value when the player in in the forest location
      // has_not_created "apple" returns TRUE if the game has never created the object with id 'apple' before.
      // --------------------------
      // The inner coade is only executed if the player typed "pick apple" or "get apple"
      // and the player is in the forest and if the apple has not been created before.
      // --------------------------
      
      : if (is_at "forest" && has_not_created "apple") {
           : print "You take an <APPLE<12>> from one of the trees." ;
           : beep millis = "100"  pitch = "0" ;
           : beep millis = "200"  pitch = "8" ;
           // put the apple in the players pocket (inventory), create + get.
           : pocket "apple";
      }
   }

   : match "examine troll;talk troll"  {
   
       // Colouring in text is possible using <sometext<n>> pattern (where n is a number between 0 and 15 representing a palette number)
       // By default 0 = black, 1 = blue, 2 = red, 3 = magenta, 4 = green, 5 = cyan, 6 = yellow, 7 = white, 8 = black, 9 .. 15 are bright versions of 1 .. 17.

      : if (is_present "troll") {
         : print "<\"I'M SO HUNGRY\"<3>>, says the enormous TROLL in the deepest possible voice." ;
      }
      : else_if (is_present "sleeping_troll") {
         : print "The troll is fast asleep." ;
      }
      
   }
   
   : match "give apple"  {
      : if (is_present "troll" && is_carried "apple") {
         : print "The troll grabs the apple from you hungrily. Unfortunately (for the troll), the apple is an <ENCHANTED APPLE<12>>, and sends the troll directly to sleep." ;
         
           // Destroying an object will move it into a non-existing state (into the ether)
         : destroy "apple" ;
         // Change the location of the troll and the sleeping troll
         // (move troll to nowhere, and sleeping_troll
         // to the location of the current troll)
         : swap o1 = "troll"  o2 = "sleeping_troll" ;
           : beep millis = "100"  pitch = "0" ;
           : beep millis = "100"  pitch = "6" ;
           : beep millis = "100"  pitch = "12" ;
           // Wait for the player to press a key, touch the screen
           // or click the mouse
         : press_any_key ;
         // Then redescribe the current location
         : redescribe;
      }
   }
   
   // If the player types 'eat apple'
   : match "eat apple"  {
      // And if the apple is present (in same location or carried)
      : if (is_present "apple") {
         // Then display a GAME OVER screen.
         // On larger games, instant death is not at all
         // advised, except if explicitly signposted perhaps.
         : print "Unfortunately, the apple was an <ENCHANTED APPLE<12>>, and you will now go to sleep - forever." ;
         : print "^r^<GAME OVER<2>>" ;
         : end_game ;         
      }
   }
}


######################################
# on_tick                            #
######################################

// The on_tick code is executed after a command has been dealt with.

on_tick {

   // is_just_entered() only returns true when the player has just
   // entered the current location (not on second tick in the same
   // location).
   : if (is_present "troll" && is_just_entered () ) {
      : beep millis = "100"  pitch = "-2" ;
      : beep millis = "100"  pitch = "-4" ;
      : beep millis = "300"  pitch = "-8" ;
      : print "The troll says, <\"THE CAVE IS MINE, GO AWAY\"<2>>." ;
   }
   
   : if (is_at "lakeside" && is_just_entered () ) {
      : print "Type <HELP<13>> to see a list of useful commands." ;
      // NOTE : Authors can override the default help screen
      // with a : match "help _" in the on_command{} section
   }

   // If the player is inside the cave, then trigger the win
   // game messages.
   : if (is_at "inside_cave" ) {

      : beep millis = "200"  pitch = "0" ;
      : beep millis = "400"  pitch = "10" ;
      // ^r^ tells adventuron to right align the text horizontally.
      : print "^r^<CONGRATULATIONS !<11>>" ;
      : print "^r^<YOU WON THE GAME !<10>>" ;
      : print "^r^<YOUR RANKING IS : JUNIOR ADVENTURER !<12>>" ;
      : end_game ;
   }
}

######################################
#  On Describe                       #
######################################

on_describe {
   // Put code here that is printed when a location is described.
}

######################################
#  Subroutines                       #
######################################

subroutines {
   // Add your subroutines here, could be useful for commonly
   // used beep commands, or decorative game over screen
}


######################################
#  Themes                            #
######################################

themes {
   my_theme : theme {
   
      // H = Header
      // G = Graphics
      // D = Description
      // X = Exit List
      // O = Object (or entity) List
      layout = H G D X O
      
      screen {
         // The space between paragraphs in terms of font height, 0.5 = half the height of the current font
         paragraph_spacing_multiplier = 0.5
      }
   }
}

######################################
# game_information                   #
######################################

// This information is used when packaging the html file
// and for determining the key to use for save slots in 
// the browser (the uuid stops save game collisions)

game_information {
   
   game_name                    = The Cave of Magic
   game_version                 = 1.0.0
   game_shortname               = Magic Cave
   written_by                   = Chris Ainsley
   year                         = 2019
   copyright_message            = The Cave of Magic was written by Chris Ainsley and is public domain.
   short_synopsis               = In the Cave of Magic, Treasure Awaits.
   
}

######################################
#  Graphics                          #
######################################


assets {

   // Graphics are base64 encoded, and graphics that
   // share an id with a location are automatically 
   // associated with that location (and shown if G
   // is included in the theme / settings / layout)
   
   // NOTE : Use the Menu button, and select Import, to import
   //        more graphics. Graphics should ideally be either
   //        128 pixels by 40 or 256 x 80 pixels (for the jam)
   //        PNG Images can be created with any tool, but pixel art 
   //        editors work best, such as https://lospec.com , choose 
   //        a consistent palette for your game.
   //        Adventuron will be getting an integrated pixel art editor
   //        in a later release.
   //        PNGs can be compressed quite nicely using https://squoosh.app/
   
   // Placeholder graphics are listed here, but graphics
   // cam be replaced with textual base64 encoded representations of 
   // PNG files.
   
   graphics {
      logo           : placeholder;
      loading_screen : placeholder;
      inside_cave    : placeholder;
      lakeside       : placeholder;
      outside_cave   : placeholder;
      forest         : placeholder;
   }
}