infocom/compilers/inform6/library/contributions/hintsms.h

! --------------------------------------------------------------------
!
! RUNTIME-HINTS-SYSTEM
! for the INFORM 6.x IF-compiler, (c) 1999 Graham Nelson
!
! Provides a Magnetic Scrolls(R)-like hints-system that decodes code-
! sequences into plain text.
!
! Written & copyright (c) 2001, 2006 by Peer Schaefer.
!
! The distribution of this file for free or for profit is allowed, as
! long as this copyright notice and the disclaimer (see below) remain
! intact. You may distribute modified versions of this file under the
! same terms, as long as you place a notice on top of the file that it
! is modified by you, and provide your name and the date of the
! modifications. The unmodified or modified version distributed by you
! must be (re)distributable, modifyable and usable under the same terms
! as this version.
!
! You may use this library unaltered or in a modified version freely
! for your own games, commercial or not. It would be nice if you give
! me some credit or provide the sourcecode, but that is not legally
! required.
!
! NO WARRANTY, NO LIABILITY. PROVIDED FREE OF CHARGE "AS IS". USE ON
! YOUR OWN RISK!
!
! Bug reports, comments and suggestions to: peerschaefer@gmx.net
!
! The latest version should be available at:
! http://www.wolldingwacht.de/if/hintsms.html
!
! --------------------------------------------------------------------



! DESCRIPTION
! ===========
! Anybody out there remembering the good old hints-system in the
! text-adventures of "Magnetic Scrolls"(R), like The Pawn and The Guild of
! Thieves? You had to type in silly things like <5x rf mz g0 5b rx oo po>
! (that are provided in the manual) on the command-prompt, and the program
! decoded that into a short hint to get you unstuck.
!
! This module provides a very similar hints-system. To encode a hint into
! a code-sequence you can use the new verb "encode", that is only available
! if you compile the game with debug-mode on. In the manual/documentation of
! your game you can provide several code-sequences that you have created in
! this way.
!
! EXAMPLE:
! You can include the following text in the manual of your game:
!    "How can I open the small chest in the throne room?
!    42 17 60 49 26 77 6c e1 e2 f7 88 55 24"
!
! To decode such code-sequence your players can use the new verb "hint".
! Typing in
! >HINT 4217604926776ce1e2f7885524
! on the prompt will result in "use a hammer".
!
! The great advantage of such hints-system is that the hints are not
! included in the game itself; the game only contains a decoder for the
! hint-code-sequences. That allows you to publish new hints for your
! games without changing the game itself.



! INSTRUCTIONS
! ============
! Include this file after parser.h
!
! This file creates two new verbs: ENCODE and HINT. The ENCODE verb is
! only available if you compile your game in debug-mode. To encode a hint
! just type ENCODE followed by your hint.
!
! EXAMPLE:
!    If you type
!    >ENCODE Hello_world!
!    on the prompt (please use the underscore _ instead of a space to
!    avoid confusing the parser), the computer will output this code-
!    sequence:
!    fa 7f f0 85 56 77 94 91 1a 77 08 9f 58
!
! To decode such code-sequence use the HINT verb.
!
! EXAMPLE:
!    If you type
!    >HINT fa7ff085567794911a77089f58
!    the result will be "hello world!". Please don't use any spaces
!    within the code-sequence to avoid confusing the parser.
!
! That's all.
!
! Bug reports, comments and suggestions to: peerschaefer@gmx.net



! HOW IT WORKS
! ============
! The encoding-engine is very primitive, but hey, we're not encoding state
! secrets here - only hints. In a first step, every character is converted
! into a numerical value. This value is scrambled by calling the ENCODE
! routine. The result is converted into a two-digit-hex-number and printed
! out. When all characters are converted, a checksum is calculated, encoded
! and printed out.
!
! EXAMPLE:
! >ENCODE test
! results in c2 7f 08 9d 70, which means:
! c2 -> a scrambled 't'
! 7f -> a scrambled 'e'
! 08 -> a scrambled 's'
! 9d -> a scrambled 't'
! 70 -> the scrambled checksum
!
! The decoding-engine reverts this process. Each hex-number is converted
! into a numerical value and this value is un-scrambled. A new checksum is
! calculated and compared with the checksum at the end of the code-sequence.
! That's it.



! And here's the code. I apologize for the mess.
! I am neither a good programmer, nor am I very familiar with Inform (nor
! is my english good). If there is a real programmer out there who can
! tidie up a bit here, I would welcome that.
! Please eMail to: peerschaefer@gmx.net




Constant codemask_increment = 19;      ! This constant is used during the
                                       ! encoding and decoding process as
                                       ! a "key". You can change it to
                                       ! create your very own hint-codes.
                                       ! It must be a constant from 1 to
                                       ! 254. I recommend primes.
Global   codemask           = codemask_increment;
                                       ! This is a global counter, used by
                                       ! the encoding and decoding routines.


! The following routine converts a two-character-hex-number into a
! numerical value. Syntax is readhex(d16,d1). d16 is the first character
! of the hex-number, d1 is the second character.
[ readhex d16 d1 hi lo;
	if ((d16>='a')&&(d16<='f')) hi=d16-'a'+10; else hi=d16-'0';
	if ((d1 >='a')&&(d1 <='f')) lo=d1 -'a'+10; else lo=d1 -'0';
	return (hi*16)+lo;
];

! Inform provides no xor-operator. I hacked this out, but there is surely
! a more elegant way. Any suggestions?
[ xor n mask a y i;
	a = 1;
	y = 0;
	for (i=1:i<=8:i++)
	{
		if ((mask&a)==0)
		{
			if ((n&a)==a) y=y|a;
		}
		else
		{
			if ((n&a)==0) y=y|a;
		};
		a=a*2;
	};
	return y;
];


! This is the decode-routine. The routine receives one numerical parameter
! and returns a numerical value. Both are in range of 1...255.
[ Decode x y a b i;
        x = xor (x, codemask);          ! First xor with codemask
        a = 1;                          ! Start with bit no. 1
        b = 128;                        ! Bit no. 8
	y = 0;

        for (i=1:i<=8:i++)              ! This loop mirrors the whole byte,
        {                               ! making bit 1 to 8, bit 2 to bit 7,
                if ((x&b)==b) y=y|a;    ! bit 3 to bit 6 etc.
                a=a*2;                  ! Next bit
                b=b/2;                  ! Previous bit
	};

        codemask = (codemask+codemask_increment)%$ff;   ! Increments codemask
        return ($ff-y);                 ! Negate and return
];


[ HintSub hintcode i checksum1 checksum2 c;
        if (WordLength(2)<4)
                "Too short hint-code.";         ! At least four characters

        hintcode = WordAddress(2);              ! Here it starts

        for (i=1 : i<=WordLength(2) : i++)      ! Only hex-digits allowed
	{
		c = hintcode->(i-1);
		if (~~( (c>='0') && (c<='9') ||
                        (c>='a') && (c<='f') ) )
			"Illegal character in hint-code (maybe a typo?)";
	};

        checksum1 = 73;                         ! Base-value of the checksum
                                                ! (This is a arbitrary value.
                                                ! You can change it to any
                                                ! value from 0 to 255.)
        codemask  = codemask_increment;         ! Reset codemask

        for (i=1:i<=(WordLength(2)-2):i++)      ! Calculate checksum
		if ((i%2)==0)
                        checksum1 = checksum1
                                    + Decode (readhex ( hintcode->(i-2),
                                                        hintcode->(i-1) ) );

        checksum2 = Decode ( readhex (                  ! Original checksum
                        hintcode->(WordLength(2)-2),    
                        hintcode->(WordLength(2)-1)
                    ) );

        if ((checksum1%$ff)~=(checksum2%$ff))   ! Checksum OK?
                "Sorry, invalid hint-code (maybe a typo?)";

        codemask = codemask_increment;          ! Reset codemask

        for (i=1 : i<=(WordLength(2)-2) : i++)  ! Main-decoding-loop
		if ((i%2)==0)
		{
                        c = Decode ( readhex (hintcode->(i-2),
                                              hintcode->(i-1) ) );
                        if (c=='_') c=' ';      ! Convert _ to space
                        print (char) c;         ! That's it!
		};
        print "^";                              ! CR
	rtrue;
];

! The following parse-routine grabs at much text as possible.
[ ParseAll;
	if (NextWordStopped()==-1)		! No text at all.
	{
#ifdef DEBUG;
                if (action_to_be==##Encode)
                        print "(Missing text for encoding.)^";
                else    print "(Missing hint-code.)^";
#endif;
#ifndef DEBUG;
		print "(Missing hint-code.)^";
#endif;
		return GPR_FAIL;
	};
	if (NextWordStopped()~=-1)		! More than one word
	{
#ifdef DEBUG;
                if (action_to_be==##Encode)
                        print "(Please use no spaces. Use underscores _ instead.)^";
                else    print "(Please use no spaces. If the code-sequence contains any spaces, just omit them!)^";
#endif;
#ifndef DEBUG;
                print "(Please use no spaces. If the code-sequence contains any spaces, just omit them!)^";
#endif;
		return GPR_FAIL;
	};
	return GPR_PREPOSITION;			! O.k.!
];

Verb meta 'hint'	* ParseAll	-> Hint;



#ifdef DEBUG;

! The following routine prints out a given 1-byte-value as a 2-digit-hex-
! number. Example: "print (hex) 255;" results in "ff".
[ hex n;
        if ((n/$10)<10) print (n/$10);
                else print (char) 'a'+(n/$10)-10;
        if ((n%$10)<10) print (n%$10);
                else print (char) 'a'+(n%$10)-10;
];

! This is the encoding-routine. The routine receives one numerical parameter
! and returns a numerical value. Both are in range of 1...255.
[ Encode x y a b i;
        a = 1;                          ! Start with bit no. 1
        b = 128;                        ! Bit no. 8
	y = 0;
        for (i=1 : i<=8 : i++)          ! This loop mirrors the whole byte,
        {                               ! making bit 1 to 8, bit 2 to bit 7,
                if ((x&b)==b) y=y|a;    ! bit 3 to bit 6 etc.
                a=a*2;                  ! Next bit
                b=b/2;                  ! Previous bit
	};
        y = xor($ff-y, codemask);       ! xor with codemask
        codemask = (codemask+codemask_increment)%$ff;   ! Increment codemask
        return y;                       ! That's it!
];

[ EncodeSub hintcode i checksum res;
	hintcode = WordAddress(2);
        checksum = 73;                          ! Base-value of the checksum.
                                                ! (This is a arbitrary value.
                                                ! You can change it to any
                                                ! value from 0 to 255.)
        codemask = codemask_increment;          ! Reset codemask
        for (i=1 : i<=WordLength(2) : i++)
	{
                res = (hintcode->(i-1));        ! Get character
                checksum = checksum + res;      ! Create checksum
                print (hex) Encode(res), " ";   ! Encode!
	};
        print_ret (hex) Encode((checksum%$ff)); ! Encode the checksum
];

Verb meta 'encode'	* ParseAll	-> Encode;

#endif;


! End.