scottkit 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 26ccefb089e59a1db6c06ff509373ed0c9f97ee1
-  data.tar.gz: ff2d2488c57754958e723dfa49274cbcb102aff6
+  metadata.gz: 74caa6f49f168820ecb2dd75e69168e99a418580
+  data.tar.gz: 7a1ff862fc3c098090fa42c9f42927742bcd1417
 SHA512:
-  metadata.gz: 988ec02e55c50a140b2347b3134e5be8d7abe69a3e6f6837c04be2ef32a792d6146f352663ffd90523c0c9d61af565911db52696615021ac7a99f4106088d6ea
-  data.tar.gz: f9bdc3f3aded8deb5f67cdef493f40294cb8ba90796ff612a0d39db5f1efa7f51453e1f50f01ad4950ce948d0327da8c2210ae5065657d5d57bc25e7ec8c835d
+  metadata.gz: 865872bd20ee18ccd2ed13af2c121de6d0932db82fb303648948a0ceb759adbd3b0c0ace1564cf54ca81e25dd015d7a4538767805badedbc144460ca103faa0d
+  data.tar.gz: f50211980fb0b774677efc29adde3d9ea3f06d1e512f126a47044998a270286ac545e5e1e53330d0c02baf11919005071ffaa375a6c8ded52cc0cd22afbb30ea

data/ChangeLog.md

@@ -1,50 +1,67 @@
-Revision history for Ruby gem ScottKit
-======================================
+# Revision history for Ruby gem ScottKit
+
+## 1.2.0 (IN PROGRESS)
+
+* Create initial tutorial, exactly equivalent to that of Games::ScottAdams.
+
+## 1.1.0 (Thu Oct 12 21:59:28 BST 2017)
+
+* Documentation fix: correctly name the `present` condition (was `accessible`).
+* Documentation fix: correctly name _twelve_ actions. (Thanks to Brian Jones for spotting the first of these.)
+    * `moveto` -> `goto`
+    * `print_noun_nl` -> `println_noun`
+    * `nl` -> `println`
+    * `clear_screen` -> `clear`
+    * `set_0` -> `set_flag0`
+    * `clear_0` -> `clear_flag0`
+    * `decrease_counter` -> `dec_counter`
+    * `add_counter` _nu`mber_ -> add_to_counter _number_`
+    * `subtract_counter` -> subtract_from_counter`
+    * `swap_loc_default` -> `swap_room`
+    * `swap_loc` -> swap_specific_room`
+    * `special` -> draw`
+
+## 1.0.0 (Wed Oct 11 21:45:27 BST 2017)
 
-1.0.0 (IN PROGRESS)
--------------------
 * Finish translating reference guide from POD to MarkDown.
 * Update reference guide to describe ScottKit format rather then Games::ScottAdams format.
 * Fix handling of darkness when playing games.
 * Support unquoted "carried" and "at" in conditions
 
-0.4.0 (Mon Mar  1 22:20:09 GMT 2010)
-------------------------------------
+## 0.4.0 (Mon Mar  1 22:20:09 GMT 2010)
+
 * Move towards using YARD for documentation instead of Rdoc.  This
   includes changes to things like the format of the Changes file.  Far
   from perfect so far: for example, plain-text documentation like
   `doc/Definition` gets mangled.
 
-0.3.0 (February 28, 2010)
--------------------------
+## 0.3.0 (February 28, 2010)
+
 * Move ScottKit out of its sub-siubdirectory in the 9Gb `mike`
   git module into its own git module.
 * Move repository hosting to github.
 * Arrange for formatted documentation to appear at
   [http://rdoc.info/projects/MikeTaylor/scottkit](http://rdoc.info/projects/MikeTaylor/scottkit)
 
-0.2.0 (February 28, 2010)
--------------------------
+## 0.2.0 (February 28, 2010)
+
 * Add `-z` option to sleep after finishing - useful when running in a
   DOS Shell under Windows, so that error messages can be seen.
 * Add facility to load a game while playing, using `#load`
 
-0.1.0 (February 28, 2010)
--------------------------
+## 0.1.0 (February 28, 2010)
+
 * Add `-p` option to compile and play a game from source.
 
-0.0.0 (February 28, 2010)
--------------------------
+## 0.0.0 (February 28, 2010)
+
 * Initial release.
 
 
-Still to do
-===========
+## Still to do
 
 * Tweak compiler to break actions when they need too many arguments as
   well as when they need too many instructions.
-* Write tutorial scaffolding.
 * Ensure that the right files are built by `YARD`
-* Write blog entry about ScottKit
 * Maybe modify to run against GLK using the Glkx driver
 * File inclusion

data/VERSION

@@ -1 +1 @@
-1.0.0
+1.1.0

data/data/tutorial/Makefile

@@ -0,0 +1,7 @@
+tutorial.md: tutorial.source.md
+	rm -f $@
+	m4 $< > $@
+	chmod ugo-w $@
+
+clean:
+	rm -f tutorial.md

data/data/tutorial/t1.map

@@ -0,0 +1 @@
+Chamber---------Dungeon

data/data/tutorial/t2.map

@@ -0,0 +1,6 @@
+Chamber---------Dungeon
+[sign]		|
+		|
+		|
+		Cell
+		[*coin*]

data/data/tutorial/t3.map

@@ -0,0 +1,6 @@
+Chamber---------Dungeon
+[sign, key]	[door]
+		=
+		|
+		Cell
+		[*coin*]

data/data/tutorial/t4.map

@@ -0,0 +1,10 @@
+Throne Room	Crypt
+[sign]		[vampire, key]
+|		|
+|		|
+Chamber---------Dungeon
+[cross]		[door]
+		=
+		|
+		Cell
+		[*coin*]

data/data/tutorial/t5.map

@@ -0,0 +1,10 @@
+		Throne Room	Crypt
+		[sign, lamp]	[vampire, key]
+		|		|
+		|		|
+Cave Mouth------Chamber---------Dungeon
+		[cross]		[door]
+				=
+				|
+				Cell
+				[*coin*]

data/data/tutorial/tutorial.md

@@ -0,0 +1,373 @@
+# ScottKit Tutorial
+
+<!-- md2toc -l 2 tutorial.source.md -->
+* [Introduction](#introduction)
+* [Stage 1](#stage-1)
+    * [Stage 1 map](#stage-1-map)
+    * [Stage 1 source](#stage-1-source)
+* [Stage 2](#stage-2)
+    * [Stage 2 map](#stage-2-map)
+    * [Stage 2 source](#stage-2-source)
+* [Stage 3](#stage-3)
+    * [Stage 3 map](#stage-3-map)
+    * [Stage 3 source](#stage-3-source)
+* [Stage 4](#stage-4)
+    * [Stage 4 map](#stage-4-map)
+    * [Stage 4 source](#stage-4-source)
+* [Stage 5](#stage-5)
+    * [Stage 5 map](#stage-5-map)
+    * [Stage 5 source](#stage-5-source)
+
+## Introduction
+
+This document walks you through the process of creating a small but complete and playable game with six rooms, seven items including a single treasure, and a couple of puzzles. It makes no attempt to be complete: you need the reference manual for that. But by the time you've worked your way through this tutorial you should be familiar with rooms, items, actions and occurrences, and you'll be ready to start writing your own games.
+
+
+## Stage 1
+
+This is the minimal playable game, consisting of rooms only - and only two of them.
+
+This stage is built entirely using the %room and %exit directives.
+
+### Stage 1 map
+
+```
+
+Chamber---------Dungeon
+
+```
+
+### Stage 1 source
+
+```
+room chamber "square chamber"
+	exit east dungeon
+
+room dungeon "gloomy dungeon"
+	exit west chamber
+```
+
+
+## Stage 2
+
+This stage introduces the first items: one portable (the coin) and one not (the sign).
+
+This stage uses the directives from the previous stage, plus `item` and `called`.
+
+### Stage 2 map
+
+```
+
+Chamber---------Dungeon
+[sign]		|
+		|
+		|
+		Cell
+		[*coin*]
+
+```
+
+### Stage 2 source
+
+```
+room chamber "square chamber"
+	exit east dungeon
+
+item sign "Sign says: leave treasure here, then say SCORE"
+
+room dungeon "gloomy dungeon"
+	exit west chamber
+	exit south cell
+
+room cell "dungeon cell"
+	exit north dungeon
+
+item coin "*Gold coin*"
+	called "coin"
+```
+
+
+## Stage 3
+
+Here we introduce the first explicitly-coded actions - the previous stages' movement between locations and ability to pick up and drop items are "intrinsics" provided by the interpreter.
+
+The new action provides the first puzzle: the player needs to unlock the cell door before entering the cell to obtain the coin. The key is necessary in order to open the door.
+
+This stage uses the directives from the previous stage, plus `nowhere`, `at`, `action` and `result`.
+
+### Stage 3 map
+
+```
+
+Chamber---------Dungeon
+[sign, key]	[door]
+		=
+		|
+		Cell
+		[*coin*]
+
+```
+
+### Stage 3 source
+
+```
+action score: score
+action inventory: inventory
+action look: look
+
+room chamber "square chamber"
+	exit east dungeon
+
+item sign "Sign says: leave treasure here, then say SCORE"
+
+room dungeon "gloomy dungeon"
+	exit west chamber
+
+item door "Locked door"
+
+room cell "dungeon cell"
+	exit north dungeon
+
+item coin "*Gold coin*"
+	called "coin"
+
+item key "Brass key"
+	called "key"
+	at chamber
+
+item door2 "Open door leads south"
+	nowhere
+
+action open door when here door and !present key
+	print "It's locked."
+
+action open door when here door
+	swap door door2
+	print OK
+	look
+
+action go door when here door2
+	goto cell
+	look
+```
+
+
+## Stage 4
+
+This stage introduces automatic actions, or "occurrences", which occur without the player needing to do anything. In effect, they happen _to_ him rather than being done _by_ him.
+
+It also uses inline documentation in the form of an action comment (though why you'd want to do this is beyond me) and specifies the start and treasury rooms explicitly.
+
+This stage uses the directives from the previous stage, plus `occur`, `comment`, `start` and `treasury`.
+
+### Stage 4 map
+
+```
+
+Throne Room	Crypt
+[sign]		[vampire, key]
+|		|
+|		|
+Chamber---------Dungeon
+[cross]		[door]
+		=
+		|
+		Cell
+		[*coin*]
+
+```
+
+### Stage 4 source
+
+```
+start dungeon
+treasury throne
+
+action score: score
+action inventory: inventory
+action look: look
+
+room throne "gorgeously decorated throne room"
+	exit south chamber
+
+item sign "Sign says: leave treasure here, then say SCORE"
+
+room chamber "square chamber"
+	exit east dungeon
+	exit north throne
+
+item cross "Wooden cross"
+	called "cross"
+
+room dungeon "gloomy dungeon"
+	exit west chamber
+	exit north crypt
+
+item door "Locked door"
+
+item key "Brass key"
+	called "key"
+	at crypt
+
+item door2 "Open door leads south"
+	nowhere
+
+action open door when here door and !present key
+	print "It's locked."
+
+action open door when here door
+	swap door door2
+	print OK
+	look
+
+action go door when here door2
+	goto cell
+	look
+
+room cell "dungeon cell"
+	exit north dungeon
+
+item coin "*Gold coin*"
+	called "coin"
+
+room crypt "damp, dismal crypt"
+	exit south dungeon
+
+item vampire "Vampire"
+
+occur when here vampire and !carried cross
+	print "Vampire bites me!  I'm dead!"
+	game_over
+	comment "vampire attacks unless cross is carried"
+
+occur when here vampire and "carried" cross
+	print "Vampire cowers away from the cross!"
+```
+
+
+## Stage 5
+
+This stage adds a light source (and darkness), a random occurrence and aliases for both verbs and nouns.
+
+This stage uses the directives from the previous stage, plus `lightsource`, `occur` with an argument, `verbgroup` and `noungroup`.
+
+### Stage 5 map
+
+```
+
+		Throne Room	Crypt
+		[sign, lamp]	[vampire, key]
+		|		|
+		|		|
+Cave Mouth------Chamber---------Dungeon
+		[cross]		[door]
+				=
+				|
+				Cell
+				[*coin*]
+
+```
+
+### Stage 5 source
+
+```
+start cave
+treasury throne
+
+action score: score
+action inventory: inventory
+action look: look
+
+room cave "cave mouth"
+	exit east chamber
+
+room throne "gorgeously decorated throne room"
+	exit south chamber
+
+item sign "Sign says: leave treasure here, then say SCORE"
+
+item lamp "old-fashioned brass lamp"
+	called "lamp"
+
+lightsource lamp
+
+room chamber "square chamber"
+	exit east dungeon
+	exit north throne
+	exit west cave
+
+# Flag 15 is on when and only when it is dark
+occur when "at" chamber and flag 15
+	clear_dark
+	look
+
+item cross "Wooden cross"
+	called "cross"
+
+room dungeon "gloomy dungeon"
+	exit west chamber
+	exit north crypt
+
+occur when "at" dungeon and !flag 15
+	set_dark
+	look
+
+occur 25% when "at" dungeon
+	print "I smell something rotting to the north."
+
+item door "Locked door"
+
+item key "Brass key"
+	called "key"
+	at crypt
+
+item door2 "Open door leads south"
+	nowhere
+
+action open door when here door and !present key
+	print "It's locked."
+
+action open door when here door
+	swap door door2
+	print OK
+	look
+
+action go door when here door2
+	goto cell
+	look
+
+room cell "dungeon cell"
+	exit north dungeon
+
+item coin "*Gold coin*"
+	called "coin"
+
+room crypt "damp, dismal crypt"
+	exit south dungeon
+
+item vampire "Vampire"
+
+occur when here vampire and !carried cross
+	print "Vampire bites me!  I'm dead!"
+	game_over
+	comment "vampire attacks unless cross is carried"
+
+occur when here vampire and "carried" cross
+	print "Vampire cowers away from the cross!"
+
+verbgroup take get
+verbgroup leave drop
+noungroup lamp lantern
+```
+
+
+## Caveats
+
+This tutorial skips a lot of details. [The reference manual](../../manual/reference.md) is indispensible for filling in the gaps.
+
+The following directives are not yet discussed: `ident`, `version`, `wordlen`, `maxload`, `lighttime`.
+
+There is not yet any discussion of flags, counters and location stores.
+
+Some discussion of what makes a good game design may be appropriate.
+

data/data/tutorial/tutorial.source.md

@@ -0,0 +1,145 @@
+changequote(`[[[', `]]]')dnl
+# ScottKit Tutorial
+
+<!-- md2toc -l 2 tutorial.source.md -->
+* [Introduction](#introduction)
+* [Stage 1](#stage-1)
+    * [Stage 1 map](#stage-1-map)
+    * [Stage 1 source](#stage-1-source)
+* [Stage 2](#stage-2)
+    * [Stage 2 map](#stage-2-map)
+    * [Stage 2 source](#stage-2-source)
+* [Stage 3](#stage-3)
+    * [Stage 3 map](#stage-3-map)
+    * [Stage 3 source](#stage-3-source)
+* [Stage 4](#stage-4)
+    * [Stage 4 map](#stage-4-map)
+    * [Stage 4 source](#stage-4-source)
+* [Stage 5](#stage-5)
+    * [Stage 5 map](#stage-5-map)
+    * [Stage 5 source](#stage-5-source)
+
+## Introduction
+
+This document walks you through the process of creating a small but complete and playable game with six rooms, seven items including a single treasure, and a couple of puzzles. It makes no attempt to be complete: you need the reference manual for that. But by the time you've worked your way through this tutorial you should be familiar with rooms, items, actions and occurrences, and you'll be ready to start writing your own games.
+
+
+## Stage 1
+
+This is the minimal playable game, consisting of rooms only - and only two of them.
+
+This stage is built entirely using the %room and %exit directives.
+
+### Stage 1 map
+
+```
+
+include(t1.map)dnl
+
+```
+
+### Stage 1 source
+
+```
+include(t1.sck)dnl
+```
+
+
+## Stage 2
+
+This stage introduces the first items: one portable (the coin) and one not (the sign).
+
+This stage uses the directives from the previous stage, plus `item` and `called`.
+
+### Stage 2 map
+
+```
+
+include(t2.map)dnl
+
+```
+
+### Stage 2 source
+
+```
+include(t2.sck)dnl
+```
+
+
+## Stage 3
+
+Here we introduce the first explicitly-coded actions - the previous stages' movement between locations and ability to pick up and drop items are "intrinsics" provided by the interpreter.
+
+The new action provides the first puzzle: the player needs to unlock the cell door before entering the cell to obtain the coin. The key is necessary in order to open the door.
+
+This stage uses the directives from the previous stage, plus `nowhere`, `at`, `action` and `result`.
+
+### Stage 3 map
+
+```
+
+include(t3.map)dnl
+
+```
+
+### Stage 3 source
+
+```
+include(t3.sck)dnl
+```
+
+
+## Stage 4
+
+This stage introduces automatic actions, or "occurrences", which occur without the player needing to do anything. In effect, they happen _to_ him rather than being done _by_ him.
+
+It also uses inline documentation in the form of an action comment (though why you'd want to do this is beyond me) and specifies the start and treasury rooms explicitly.
+
+This stage uses the directives from the previous stage, plus `occur`, `comment`, `start` and `treasury`.
+
+### Stage 4 map
+
+```
+
+include(t4.map)dnl
+
+```
+
+### Stage 4 source
+
+```
+include(t4.sck)dnl
+```
+
+
+## Stage 5
+
+This stage adds a light source (and darkness), a random occurrence and aliases for both verbs and nouns.
+
+This stage uses the directives from the previous stage, plus `lightsource`, `occur` with an argument, `verbgroup` and `noungroup`.
+
+### Stage 5 map
+
+```
+
+include(t5.map)dnl
+
+```
+
+### Stage 5 source
+
+```
+include(t5.sck)dnl
+```
+
+
+## Caveats
+
+This tutorial skips a lot of details. [The reference manual](../../manual/reference.md) is indispensible for filling in the gaps.
+
+The following directives are not yet discussed: `ident`, `version`, `wordlen`, `maxload`, `lighttime`.
+
+There is not yet any discussion of flags, counters and location stores.
+
+Some discussion of what makes a good game design may be appropriate.
+

data/manual/reference.md

@@ -459,7 +459,7 @@ of an item defined somewhere in the ScottKit file.
 --
 True if _ITEM_ is in the player's current room.
 
-* `accessible` _ITEM_
+* `present` _ITEM_
 --
 True if _ITEM_ is either being carried by the player or in the
 player's current room (i.e. if either `carried ITEM` or `here
@@ -504,7 +504,7 @@ The sense of the
 `at`,
 `carried`,
 `here`,
-`accessible`,
+`present`,
 `exists`,
 `moved`,
 `loaded`,
@@ -530,7 +530,7 @@ necessary, to place each result on its own line.
 
 The following opcodes are supported:
 
-* `moveto` _room_
+* `goto` _room_
 --
 Moves to the specified _room_ and displays its description.
 
@@ -538,7 +538,7 @@ Moves to the specified _room_ and displays its description.
 --
 Redisplays the description of the current room, the obvious exits and
 any visible items. This is done automatically whenever the player
-moves (with the `moveto` action), `get`s an item from the current
+moves (with the `goto` action), `get`s an item from the current
 room, or `drop`s an item. So far as I can tell, it need only be done
 explicitly when changing the value of the darkness flag.
 
@@ -625,15 +625,15 @@ Prints "The game is now over", waits five seconds and exits.
 --
 Prints the noun that the user just typed.
 
-* `print_noun_nl`
+* `println_noun`
 --
 Prints the noun that the user just typed, followed by a newline.
 
-* `nl`
+* `println`
 --
 Emits a newline (i.e. moves to the beginning of the next line).
 
-* `clear_screen`
+* `clear`
 --
 Clears the screen. Who could have guessed?
 
@@ -675,12 +675,12 @@ Sets flag 15, which indicates darkness. Exactly equivalent to
 Clears flag 15, which indicates darkness. Exactly equivalent to
 `clear_flag 15`.
 
-* `set_0`
+* `set_flag0`
 --
 Sets flag 0. Exactly equivalent to
 `set_flag 0`.
 
-* `clear_0`
+* `clear_flag0`
 --
 Clears flag 0. Exactly equivalent to
 `clear_flag 0`.
@@ -698,19 +698,19 @@ drivers can't print values greater than 99, so if you're designing
 your games for maximum portability, you should avoid using numbers
 higher than this.
 
-* `decrease_counter`
+* `dec_counter`
 --
 Decreases the value of the currently selected counter by one. The
 value cannot be decreased below zero. Surprisingly, there is no
-corresponding `increase_counter` action, but you can use `add_counter
+corresponding `increase_counter` action, but you can use `add_to_counter
 1`.
 
-* `add_counter` _number_
+* `add_to_counter` _number_
 --
 Increases the value of the currently selected counter by the specified
 _number_.
 
-* `subtract_counter` _number_
+* `subtract_from_counter` _number_
 --
 Decreases the value of the currently selected counter by the specified
 _number_.
@@ -718,28 +718,29 @@ _number_.
 * `select_counter` _number_
 --
 Chooses which of the sixteen counters is the current one. Subsequent
-`decrease_counter`, `print_counter`, etc., actions will operate on
+`dec_counter`, `print_counter`, etc., actions will operate on
 the nominated counter. (Initially, counter 0 is used.)
 
-* `swap_loc_default`
+* `swap_room`
 --
 Swaps the player between the current location and a backup location.
 The backup location is initially undefined, so the first use of this
-should be immediately followed by a `moveto` to a known room; the
+should be immediately followed by a `goto` to a known room; the
 next use will bring the player back where it was first used.
 
-* `swap_loc` _number_
+* `swap_specific_room` _number_
 --
-Like `swap_loc_default` but works with one of a sixteen numbered
+Like `swap_room` but works with one of a sixteen numbered
 backup locations, nominated by _number_. Swaps the current location
-with backup location _number_, so that subsequently doing `swap_loc`
+with backup location _number_, so that subsequently doing `swap_specific_room`
 again with the same argument will result in returning to the original
 place. This can be used to implement vehicles.
 
-* `special` _number_
+* `draw` _number_
 --
-Performs a "special action" that is dependent on the driver. For
-ScottFree, this does nothing.
+Performs a "special action" that is dependent on the driver. For some
+drivers, it draws a picture specified but the number. In
+ScottKit (as in ScottFree), this does nothing.
 
 * `continue`
 --
@@ -897,8 +898,8 @@ first.
 
 ## See also
 
-* The top-level [README](file.README.html)
-* [The ScottKit tutorial](file.tutorial.html) (XXX not yet written)
+* The top-level [README](../README.md)
+* [The ScottKit tutorial](../data/tutorial/tutorial.md)
 * The Perl module [Games::ScottAdams](http://search.cpan.org/~mirk/Games-ScottAdams/)
 
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: scottkit
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Mike Taylor
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-10-11 00:00:00.000000000 Z
+date: 2017-10-13 00:00:00.000000000 Z
 dependencies: []
 description: ScottKit is a toolkit for compiling, decompiling and playing adventure
   games in the Scott Adams format.
@@ -61,13 +61,21 @@ files:
 - data/test/t7.sao
 - data/test/t7.solution
 - data/test/t7.transcript
+- data/tutorial/Makefile
+- data/tutorial/t1.map
 - data/tutorial/t1.sck
+- data/tutorial/t2.map
 - data/tutorial/t2.sck
+- data/tutorial/t3.map
 - data/tutorial/t3.sck
+- data/tutorial/t4.map
 - data/tutorial/t4.sck
+- data/tutorial/t5.map
 - data/tutorial/t5.sck
 - data/tutorial/t6.sck
 - data/tutorial/t7.sck
+- data/tutorial/tutorial.md
+- data/tutorial/tutorial.source.md
 - lib/scottkit/compile.rb
 - lib/scottkit/decompile.rb
 - lib/scottkit/game.rb