Spelunky v1.3

http://forums.tigsource.com/index.php?topic=28467.0

This is an unofficial multi-platform update of Spelunky. It can be compiled
for both Windows and Mac OS X without editing the game's source code. Every
effort has been made to preserve the gameplay of Spelunky in it's original
form. However, some changes have been made to the source code to fix bugs
or optimize for ease of use and development. This update was created by
idyll with assistance from the Spelunky community. See the "OldReadMe.txt"
for the original introduction to Spelunky by Derek Yu.

Windows binaries are compiled with Game Maker Standard 8.1.141 r11549
Mac binaries are compiled with Game Maker Pro for Mac OS X 7.5.87


=========================
 CHANGE LOG
=========================

--------------------
 v1.3
--------------------

- Added version number and disclaimer to title screen
- Replaced Super Sound System with Caster extension for cross-platform
  playback of audio files.
- Sorted source code assets into folders
- Fixed transparency and other issues with sprites
- Fixed title music not looping after intro sequence
- Fixed hint hand not appearing under certain conditions
- Added "Test" button to Config for testing chosen video settings
- Renamed "Resolution:" subtitle in Config to "Scale:"
- Fixed Config not asking for "Jump" button when gamepad without analogue
  sticks is configured
- Added "Joyconfig" button behavior to enable "Use gamepad" in Config
- Converted source code to Game Maker 7 format (1)
- Disabled F4 and F9 keys (2)
- Changed default screen scale to "X2" (3)
- Removed references to "Flare" key/button in Spelunky and Config code (4)
- Fixed Damsel making sound when dead and bounced, but not when alive (5)

--------------------
 v1.3 MAC ONLY
--------------------

- Changed location of config files and "levels" folder to
  "~/Library/Preferences/Spelunky"
- Moved "sound" folder to "Spelunky.app/Contents/Resources"
- Fixed graphical glitch in dark levels
- Fixed "Enter" key not registering in "Level Editor" and "Load Level"
- Fixed "Fit screen" scale in windowed mode (6)
- Added "Alt" key modifier to function keys while in windowed mode (7)
- Fixed "Start game on exit" in Config with GMac-Terminal extension (8)

--------------------
 FOOT NOTES
--------------------

(1) Game Maker for Mac is a port of the Windows version of Game Maker 7.
    Converting the Spelunky source code from Game Maker 8 to Game Maker 7
    format was necessary to make this game run on Mac. I was unable to get
    Spelunky to run in Game Maker Studio and I didn't want to restrict
    source code changes to a newer version of Game Maker that most people
    don't yet own. If you make any edits to the source, please do so within
    Game Maker 7, Game Maker for Mac or LateralGM so that Mac users can
    make use of any changes you implement. Converting from Game Maker 8 to
    Game Maker 7 format with LateralGM requires setting the transparency by
    hand for all the sprites and backgrounds that need it. This was a real
    pain!

(2) These keys should be re-enabled in "Global Game Settings" when
    compiling the code as a Windows executable. Besides Mac using the
    function keys for other behaviors by default, using F4 to switch
    between windowed mode and fullscreen causes graphic corruption. This
    seems to be an issue with Game Maker for Mac. F9 is unneeded since Mac
    has several built-in keyboard shortcuts to save screenshots to the
    Desktop in various file formats.

(3) Unlike the original default of "X3" screen scale, "X2" worked fine in
    fullscreen mode with every resolution I tried.

(4) The "Flare" key/button would have functioned like the "Bomb" and "Rope"
    keys/buttons, but it was not used in the final 1.1 version of the game.
    However, there were still references to it in the source code. Config
    and Spelunky would assign a default value to the "Flare" key/button and
    check for it's value in the config files. Config also wrote the default
    value it assigned to the "keys.cfg" and "gamepad.cfg" files. All
    references to the "Flare" key/button have been commented out or
    deleted. You should delete any old "keys.cfg" or "gamepad.cfg" files
    and reconfigure your keys/buttons in Config.

(5) The Damsel, when dead and bounced on the ground, would make a sound,
    but not when alive. This behavior was the opposite of enemies you can
    carry, so I assumed it was a bug. Thanks to TyrOvC for helping me fix
    this issue.

(6) The original softfullscreen code doesn't work on Mac. Window borders,
    window icons and the Menu bar can't be hidden by Game Maker for Mac.
    This is now taken into account when calculating the scale of
    "Fit screen" while in a window. Turn hiding on for the Mac "Dashboard"
    and you'll have the largest play area possible in windowed mode.

(7) Mac treats function keys differently than Windows. Many of them are
    assigned a particular behavior by default. These behaviors take
    priority when Spelunky is running in a window. Asking the player to
    disable the function keys or modifying system config files while
    Spelunky is running seemed like a bad idea.  :)  Instead, when playing
    Spelunky in windowed mode, the player must hold down the "Alt" key
    before using a function key. The function keys still work without the
    "Alt" key when Spelunky is fullscreen.

(8) The GMac-Terminal extension is used in Config to execute Spelunky when
    the "Start game on exit" box is checked. This extension allows access
    to Mac "Terminal" commands. Allowing Config access to the "Terminal" is
    potentially dangerous, but I've experienced no ill effects from using
    this extension. Game Maker for Mac's built-in function to run external
    programs appears to be broken.


=========================
 KNOWN ISSUES
=========================

"Fit screen" scale is not always pixel accurate in fullscreen mode and some
pixels on screen may appear double their actual width. "X2" scale in
fullscreen mode is now the default because it should behave as intended for
most resolutions.

Sometimes, when using the "Level Editor" in fullscreen, your mouse cursor
can't move past an invisible wall on the bottom right side of the screen.
This is caused by using a scale that's too small for your display
resolution. Try a bigger scale like "X4" or "Fit screen."

Rapidly entering and exiting water can cause bats to fly instead of hanging.

Occasionally, vines don't disappear and lamps don't drop after the block
above them is destroyed.

--------------------
 MAC ONLY
--------------------

Gamepads don't work with the Mac version of Spelunky because of a
limitation in Game Maker for Mac. It appears that YoYo Games is aware of
the issue, but is unwilling or unable to fix it.

http://gmc.yoyogames.com/index.php?showtopic=526340&view=findpost&p=3897446

This issue still exists in the latest version of Game Maker Studio as of
this writing.

http://gmc.yoyogames.com/index.php?showtopic=540582&view=findpost&p=3964074

I find Spelunky much easier to control with a gamepad. I recommend using an
app such as ControllerMate to translate your gamepad button presses into
keystrokes.

The "Fit screen" scale behaves strangely in fullscreen mode. I tried this
setting with two different Macs each with a widescreen monitor. With the
first Mac the play area was shifted all the way to the left and had a large
black bar on the right side of the screen. Normal behavior is two black
bars on either side of the play area. The second Mac stretched the play
area to fill up the entire screen. I didn't see this behavior with these
settings in the Windows version of Spelunky. I assume this is a problem
with Game Maker for Mac.

The "period" key acts like the "Delete" key in the "Level Editor" and
"Load Level" screens. Do you really need periods in your custom level
names?


=========================
 SOURCE CODE
=========================

1. When I open the source code in Game Maker it produces an error that
   says: "Cannot find extension package: Caster" and/or "GMac-Terminal."
   Why?

   This new version of Spelunky requires the Caster extension for audio
   support in both Windows and Mac. The GMac-Terminal extension is also
   required if you are compiling Config for Windows or Mac. Game Maker for
   Windows does not actually use the GMac-Terminal extension, but it must
   be installed. These extensions are provided with the Spelunky source
   code for your convenience. You can find them in the "Extensions"
   directory.

2. Why do I get an error about "OpenAL32.dll" when I try to run Spelunky
   and/or Config?

   The Caster extension requires certain "dll" files to function within
   Windows. These "dll" files are located in the "CasterDlls.zip" file in
   the "Extensions\Caster" folder. Extract its contents to the same
   directory as the "gmk" files to fix this error.

3. Why is there no sound when I run the Spelunky source code from within
   Game Maker?

   Did you install the required Caster extension? See the answer to
   question one above.

4. Why do I get an error about "Unknown function or script: run_terminal"
   when I run the Config source code from within Game Maker?

   Did you install the required GMac-Terminal extension? See the answer to
   question one above.

5. What is the "LastCompileStep.command" file in the "MacOSX" directory?

   It is a script that prepares the compiled Mac version of Spelunky for
   distribution. If you're compiling the source code on a Mac, create the
   "Config.app" and "Spelunky.app" executables in the same folder as the
   "gmk" files. Open the "Terminal" and type the following to make the
   script executable:

   chmod +x Path/to/MacOSX/LastCompileStep.command

   Double click the "command" file in "Finder" and it should run. The
   script will delete unneeded files and copy the sound and icon files into
   the apps. It will also delete the Game Maker runner in "Config.app" and
   create a relative symbolic link to the runner in "Spelunky.app." This
   means that Config must be executed from the same directory as Spelunky
   or it will not run. The benefit of this is a savings of 17.7 megabytes.
   No point in increasing download times or wasting hard drive space,
   right?

6. Why don't F4 and F9 work any more?

   These keys are disabled by default because they cause problems when used
   on a Mac. You should re-enable these function keys in Game Maker under
   "Global Game Settings" when compiling the source code as a Windows
   executable.

7. Why doesn't the executable I created have the "Spelunky/Gold Idol" icon?

   Icon formats are not compatible across Windows and Mac. The icons for
   both Windows and Mac are located in the "Icons" directory. Point Game
   Maker for Windows at the "Windows.ico" file and Game Maker for Mac at
   the "MacOSX.icns" file.

8. Why is the source code in Game Maker 7 format? Game Maker 8.1 is better!

   While I agree that Game Maker 8.1 is faster and has less bugs, the Game
   Maker 8 and 8.1 file format isn't supported by Game Maker for Mac. Even
   though the source code is in Game Maker 7 format it must be compiled
   with Game Maker 8.1 or newer to run in Windows. See the question below
   for more information.

9. Why do I get an error about "Unknown variable os_type" when I try to run
   the source code with Game Maker 7 or 8?

   Unfortunately, Game Maker 7 for Windows can only be used to edit the
   source code and not test it. The code makes use of the "os_type"
   function to discover which operating system it is running on. This
   function was introduced in Game Maker 8.1 for Windows and Game Maker for
   Mac. Since Game Maker 7 and 8 don't support "os_type," both will display
   an error if you try to run the source code as is.


If you wish to edit the source code and submit your changes to this project
please do so by posting your code on the forum where this project resides.

http://forums.tigsource.com/index.php?topic=28467.0

Please document the line numbers and asset names of whatever you change,
add or delete. I am trying to keep an accurate log of all the changes made.

Feel free to use the source code as you see fit provided that such use
doesn't violate the licenses listed below.

=========================
 LICENSES
=========================

--------------------
 SPELUNKY
--------------------

You can redistribute and/or modify Spelunky, including its source code,
under the terms of the Spelunky User License. You may not sell Spelunky.

Spelunky is distributed in the hope that it will be entertaining and
useful, but WITHOUT WARRANTY. Please see the Spelunky User License for
more details.

The Spelunky User License should be available as an external file called
COPYING. If not, please obtain a new copy of Spelunky from the official
website at http://spelunkyworld.com/

--------------------
 CASTER
--------------------

Caster is free for any kind of use, but credits to MoaCube and Marius
Utheim are necessary.

--------------------
 GMAC-TERMINAL
--------------------

Copyright © 2010, The GMac Project All rights reserved. Redistribution and
use in source and binary forms, with or without modification, are permitted
provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice,
   this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.

3. All advertising materials mentioning features or use of this software
   must display the following acknowledgement: This product includes
   software developed by the GMac Project. www.gmacorg.sourceforge.net

4. Neither the name of the GMac Project nor the names of its contributors
   may be used to endorse or promote products derived from this software
   without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE GMAC PROJECT "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN
NO EVENT SHALL THE GMAC PROJECT BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.


=========================
 THANKS
=========================

to Derek Yu and everyone that contributed to the creation and testing of
Spelunky

to TyrOvC for creating Spelunky v1.2r2 which was the basis for this
update's code

to Moloch, halibabica, Delver and other members of the Mossmouth forums
that provided fixes, updates, bug reports, testing and advice

to Leon Arnott for his Mac OS X port of Spelunky v1.0 that inspired this
update

to MoaCube and Marius Utheim for their Caster extension that gives Spelunky
sound across multiple platforms

to The GMac Project for providing a "Terminal" extension to Game Maker for
Mac

to YOU, for giving this great game a chance  :)