README

Gutsy Storm is the codename for an otherwise nameless game project which
is basically me having fun with blocky/voxel, procedurally generated terrain
similar to Minecraft. This is not intended to be a Minecraft clone. Right now
I'm enjoying just messing around with the core engine code. Eventually, the plan
is to use Minecraft-like terrain and terrain editing functionality for an
Action-RPG style game. So, this will eventually be a bit of a Diablo clone with
a Minecraft-style voxel world. In any case, there's a vast distance between
where the application is today and that eventual goal.

Author: Andrew Fox <foxostro@gmail.com>
Project Home: <http://github.com/foxostro/GutsyStormCocoa>


Getting Started
===============
To build the game, just open it in Xcode and run! There is no bootstrap step.
There are no external dependencies.


Instructions
============
* Move the mouse to place a cursor on the terrain.
* Use the WASD keys to move around in space.
* Press 'b' to remove the block under the cursor.
* Press Space Bar to place a block under the cursor.
* Press 'c' and 'v' to add and remove torches under the cursor. These are not
  currently represented with any object or marker besides their effects on
  lighting.
* Press 'y' and 'u' to have the game act as if a memory pressure notification
  was received. This is useful for testing the behavior of the application in
  memory pressure conditions. Also, you might consider looking at the
  memory_pressure(1) command-line tool.
* Press 'p' to print information to the console about the terrain object.


System Requirements for Using Gutsy Storm
=========================================
The game has been tested on three machines:
 * MacBookPro5,1
 * MacBookPro11,2

In normal circumstances, there is a working set of voxel and geometry data
which must be held in memory at all times and a set of data which is held purely
for caching. The cache will be expanded and contracted automatically based on
the amount of memory available on the system. So, the working set is the real
concern here, especially if it is too large to hold in memory on your machine.

If the frame rate is very low then there are two things you might want to try:

1. Make sure you are running a Release build, not a Debug build.
2. Try lowering the size of the "active region" by entering the following in
   Terminal:

    % defaults write ~/Library/Containers/com.foxostro.GutsyStorm/Data/Library/Preferences/com.foxostro.GutsyStorm.plist ActiveRegionExtent -int 128

   You may also want to this with a value of "64" or "192".
   (The default is 256.)

Also, the active region size controls the draw distance of the terrain, so
reducing this value can improve performance by reducing load to the GPU.

Additionally, geometry for each chunk in the active region is uploaded to the
GPU the first time the chunk is drawn. This can cause an unacceptably low frame
rate while the active region is being generated. In this case, once chunk
generation is finished, the frame rate will return to normal. This issue can be
considered a performance bug as I can probably schedule VAO creation more
effectively.


Benchmarking
============
To run a suite of performnace benchmarks, set the boolean "Benchmark" default to
YES. This facility exists because it was much more convenient to make my own
performance benchmark test harness than to get Xcode to actually run my XCTest
performance tests in Release mode.

To enable detailed logging of the time spent in user actions, set the boolean
default "StopwatchTraceEnabled" to YES. This will cause the application to log
to the console when a user action occurs and to log how long each intermediate
step takes to run. Note that this functionality is disabled when the app is
built with the GS_STOPWATCH_TRACE_STEP_ENABLED macro set to 0, which is the
default. See GSActivity.h for details.


Misc. Notes
===========
Tileset artwork comes from the article at <http://blog.project-retrograde.com/2013/05/marching-squares/>.