file_id.diz
DESCENT - The quest for NOM
A LOLCODE demo for Breakpoint 2010
Written by Valerio "Karoshier" Cannone on march 2010
-----
LICENSE
-------
This work is distributed under the terms of the Creative Commons Attribution
Non-Commercial Share-alike 3.0 license. To have more information on the
terms under which you can use this work, please visit the following address:
http://creativecommons.org/licenses/by-nc-sa/3.0/
To view the full legal licensing terms please visit the following address:
http://creativecommons.org/licenses/by-nc-sa/3.0/legalcode
BEHIND THE SCENES AND TECH STUFF
--------------------------------
I've written this demo in one week man time, from scratch and with absolutely
no previous knowledge of the LOLCODE language. I've done this for pure fun.
The specification of the language can be found at http://www.lolcode.com
There's a wide variety of interpreters and compilers available for LOLCODE,
most of which are mainly written in high level scripting languages.
Each single interpreter and compiler supports its own declination of the
language, mostly due to the fact that the language itself has evolved during
time and the definition process is still wildly in progress.
*YES*, the language is still in its infancy.
One of the main limitations of the LOLCODE language is that there is no way
(yet) to alter the shell screen except for outputting characters to STDOUT.
Since no escape character is accepted by the language, there's no way to move
the cursor around, clear the screen, change the color of the text or stuff like
that. The only option to display something is therefore to let the previous
text lines to scroll up as you add more characters via STDOUT.
The language allows loading of libraries via the CAN HAS <library>?
instruction. However, since the language does not support pointers, system
calls or stuff like that, having a STDIO library not actually able to use
STDIN, STDOUT and STDERR would be pointless and that's why the CAN HAS
instruction is implemented in most of the interpreters but actually does
nothing at all. As a matter of fact, I've not included CAN HAS STDIO? in my
code and everything works correctly because the VISIBLE, INVISIBLE and GIMMEH
functions are hardcoded into the parser instead of relying on an external
library. As a further consequence of not being able to load libraries, the
whole code must reside into one single file.
The language does not allow classic comparison constructs like <= and >=,
therefore this has to be worked around as suggested on the lolcode web site
by using the equal, not equal, max and min constructs.
Pointers are not supported as well, which prevents several "standard" C/C++
tricks to be used when organizing and accessing data inside the code.
The 1.3 version of the specification adds BUKKITs which are basically
dynamic arrays of variants. BUKKITs could theoretically be combined to form
multi-dimensional arrays but I've choosen to stick with monodimensional
ones for several reasons.
There is also no way in lolcode to define a block of constant data, and
this forced me to define empty arrays for sprite data and fill them manually
during the initialization phase. This is what makes the DESCENT.LOL file
200+ kilobytes in size compared to the 50+ kilobytes of actual hand-written
source code. Math functions are also not availabe, except for the basic
ones: addition, subtraction, multiplication, division and module.
THE PARSER USED TO RUN THE DEMO
-------------------------------
I've choosen Justin J. Meza's parser because of several reasons:
* It's faster than other interpreters as it's written in C rather than in
a scripting language, and its code has been developed with speed in mind.
* It supports basically everything from the 1.2 version of the language as
well as something from the 1.3 version; including BUKKITs, without which
it would have been hardly possible to do any demo at all.
* It's a breeze to use, requiring nothing more than its executable and a text
editor.
* Can be compiled in Windows, *nix and basically everywhere you can have a C
compiler with the standard library available.
* Its source code is available for download, which helped me figuring out
what was wrong when I had nasty bugs in my script.
You can find Justin J. Meza's parser at http://www.icanhaslolcode.org
Due to the several declinations available, I don't think this demo would run
with something different than Justin's parser. I've included a copy of
the parser's binary executable in the demo archive, but you can find updated
versions and source code at http://www.icanhaslolcode.org
CONFIGURING THE DEMO TO RUN CORRECTLY
-------------------------------------
Before running the demo, you must configure the code for your shell size
and processor speed. This can be done by text-editing the file DESCENT.LOL
and searching for the string "CONFIGURE HERE!" (without quotes).
Chanege the value of HORZSIZE, VERTSIZE and MASTERTIMING to suit your shell
and processor. HORZSIZE defines how many characters the shell will display
in a row before wrapping to the next one. VERTSIZE defines how many rows
can be displayed by the shell without scrolling up one row. MASTERTIMING is
a delay value that is used to slow down the display scrolling and wait for
some time when needed.
The standard Windows shell is 80 by 25 characters when displayed in a window.
If you hit ALT+ENTER to maximize the shell window to full screen, then the
"resolution" of the shell will be different. On my PC I have a 1920x1080
display, and when the shell is maximized it shows 80 by 50 characters. Please
note that the demo does not use the last row of the display but you should
count it anyway as the demo subtracts 1 from VERTSIZE when it starts in order
to account for this.
With regard to the processor speed, the value 8192 is good for my machine but
according to your processor speed you might require a smaller or a bigger
value. My PC has a dual core 2.2GHz processor; the faster your processor, the
higher the value assigned to MASTERTIMING should be. The number of cores you
have in your machine is not important and that's because the parser is
single-threaded and will therefore only use one core anyway. Dual or quad
cores therefore don't matter; only the speed of the single core does. I hope
this is enough of a hint because the right value has to be found
experimentally. As a rule of thumb however, you can compute the value to use
for MASTERTIMING with a simple proportion using the data I have reported
above.
For your comfort I have added a test mode to the demo code which should make
this mandatory configuration a little easier.
TESTING THE DEMO CONFIGURATION
------------------------------
Run the demo, then press 1 and hit enter. This will display a border around
the screen to verify that the whole display area is being used. If the
configuration is correct, you'll see a rectangle filling the shell screen
with some text in the middle of it and some more below the rectangle.
If VERTSIZE is wrong, the rectangle will either be non completely visible or
will not fit the screen vertically. If HORZSIZE is wrong, the rectangle will
appear horizontally distorted.
If everything looks good then hit enter, otherwise hit CTRL+C twice and change
the values in DESCENT.LOL then retry.
The second test screen will show some text and then the last row of the scren
gets slowly filled with dots. The test will automatically end when the entire
row has been filled with dots and allows you to check if MASTERTIMING is set
correctly. It should take approximately one second to display each single dot.
If dots show up too fast, then increment the value of MASTERTIMING; if dots
show up too slow, then decrement the value of MASTERTIMING.
RUNNING THE DEMO
----------------
* The demo can be run by either double-clicking on the RUNME.BAT file or by
opening a DOS shell and typing "lolcode.exe -f descent.lol"
* In Windows, you can toggle the full screen mode by pressing ALT+ENTER
while the demo runs
* When prompted to do so, press ENTER to start the demo. If you want to run
the test routine, press 1 and then ENTER instead of just pressing ENTER.
* Stop the demo at any time by hitting CTRL+C twice or wait for the demo to
finish and return to the shell prompt on its own.
KNOWN ISSUES
------------
While the demo is running, the parser will constantly and quickly eat memory.
This is due to a bug in the parser and Justin is already working on a
solution to that. You'll soon be able to download a fixed version of the
parser at http://www.icanhaslolcode.org
In the meanwhile...
On my 2.2GHz CPU, with MASTERTIMING set to 8192 and the demo running in an
80x25 Windows OS shell, the apex of memory consumption reaches 1.5GB.
On a 3.3GHz CPU, with MASTERTIMING set to 12288 and the demo running in an
80x50 full-screen Windows OS shell, the apex of memory consumption is expected
to reach 1.8GB.
Altough this can seem absolutely weird and pointless, at the moment a machine
with at least 2GB of RAM memory is absolutely necessary. If you don't have
enough RAM available, the parser will eventually reach a memory-full state
and Windows will negate further memory allocation. This will cause abrupt
termination of the parser process and will therefore terminate the demo.
