AdaGate Files

=================================================================
AdaGate v 4.3 beta  11nov2015
=================================================================
What's new (newest at top of this list):

.................... ver 4.3 -- 11nov15 ........................................
. Eye level on beach now varies to match ground contours.
. ZPM on beach now also follows ground.

.................... ver 4.2 -- 10nov15 ........................................
. Beach prolog now has receptacle and kickable zpm (beachball);  beach rocks are now obstacles.  Reminder:  in case I forget, please delete the file ./data/resume_ag.txt before running the game for the first time.  This will insure you start at the beginning and at the easiest puzzle level!

.................... ver 4.1 -- 15oct15 ........................................
. Elliminated one remaining call to SDL_Init with parameter SDL_INIT_EVERYTHING, that had inadvertently escaped my notice.  This should enhance the portability of the delivered binary according to linux-app-checker.
. Bumped epilog water dimension to 200 since the graphical burden is acceptable.

.................... ver 4.0 -- 02sep15 ...........................................
. revised models for island sand and ocean water for improved appearance and support on all hardware, including old MacBooks and Retina displays @highDPI.  This elliminates triangular artifacts in ocean as well as problems with jerky movement.
. seaweed now surrounds nose of Electra cockpit and better matches the sand contours;  
. moved crab, starfish to surfline;
. improved shark and fish textures.
. improved water in epilog.

.................... ver 3.9 -- 13aug15 .............................................
. Improved realism by adding a glsl "uniform" value that is passed to the various fragment shaders that governs the brightness of island objects, like trees and sand, so that the night version is appropriately darker due to less ambient light.
. added seaweed near airplane.
. improved tree, fish, and stargate textures using glsl "discard" statement.
. minor improvements to ocean appearance due to shader tweaks.
. Reminder for Mac Retina users:  the beach scene may be jerky due to a heavy graphical burden in highDPI mode.  Graphical quality is still great even if you set lowDPI mode.

.................... ver 3.8 -- 27jul15 .............................................
. Now using multiple calls to SDL_PumpEvents to preclude an erroneous popup dialog in Gnome-Gnu-Linux that claims that the application is not responding.
. Added a dominant island-concentric wave form to the ocean to improve the action of the surf all around the island.  But, the ocean quad-count had to be increased to avoid obvious triangles in the surf.  The graphical burden of the beach scene is now greater and may cause noticeable jerkiness on Mac Retina displays when in HighDPI mode.  See line 387 in gametypes.ads to adjust ocean refinement level yourself prior to recompiling.  Note that highDPI mode on Macs can be turned off for smoother performance.
. Improved the ocean water frag shader in two ways:  a) opacity now depends on slant-depth rather than vertical depth;  b) added a pseudo-Fresnel effect by varying opacity [and thus reflectivity?] according to the angle between the line-of-sight and the water surface normal.
. Added low hanging fog or smoke to each dungeon.

.................... ver 3.7 -- 11jul15 .............................................
. Elliminated jerky movements due to excessive graphical burden.  This involved either reducing the size of the dynamic-wall-scenes, using less graphically-intense scenes, and reducing the triangle count in level 0,5 water.  This problem was particularly noticable in highDPI mode, eg. on MacBooks.
. Equilibrated [increased] volume of the beach sounds.
. These problems tell me I need testers!  Please send feedback, if possible.
. Now using proper SDL-flag for full-screen mode.

.................... ver 3.6 -- 07jul15 .............................................
. added new file ~/data/solns.sok that contains all sokoban puzzle solutions;
. slight improvements to ocean appearance, particularly at night;
. removed Amelia-sky because Niku-VIII was a bust.  The underwater ROV malfunctioned so we may never know whether the anomaly at 300 feet was her fuselage.  Only the freckle cream remains :(
. now ZPMs light up whenever they contact a receptacle.
. Fixed logic error in movement physics code.
. Improved island water opacity.

.................. 3.5 1apr15 .........................................
. One more try...from an actual trial on a "clean" [opensuse] install, I found that further changes were required to be able to compile and run.
	. modified the call to SDL_Init so only needed systems are initialized;
	. improved the linux compile script and added comments to enhance the likelihood that it will work on a user's machine, with a minimum of changes.

. updated AppChk compatibility log [for delivered linux exe]:
	. fedora 15-18
	. openSUSE 12.1, 12.2, 12.3
	. ubuntu 12.10, 13.04
	. ubuntu 14.04 (build machine)
	. openSUSE 13.2 (my trial install machine)

.................. 3.4 31mar15 .........................................
. Corrected errors that resulted in bad linux executables that would not run on any client machine.  Now they should run on recent distributions of fedora, opensuse, ubuntu, and perhaps others.
. Restored the proper softlink structure in the delivered libraries.
. Note that the Mac executables do not have any such problem.

.................. 3.3 26mar15 .........................................
. More completely tested and validated:  Enabled OS-X builds on any Mac with a recent version of OS-X that has a GNU Ada compiler [GNAT] installed.  Static libs for all nonstandard libraries are delivered along with a new build script "ocmplls.sh" to enable this capability.  All other libraries needed are OS-X-standard frameworks.

. More completely tested and validated:  Similarly, after installing GNAT, most linux distros are now capable of building adagate with the updated linux build script "lcmplld_ag.sh".  And the delivered executables should run on recent versions of fedora, opensuse and ubuntu.

....................... 3.2 24mar15 ......................................
. Began testing with "linux app checker" and found that static linking was useless for gnu/linux apps since they were not compatible with any distro.  So now only one exe is delivered for linux which run [assuming SFML, SDL2] on:
	. fedora 15-18
	. opensuse 12.1, 12.2
	. ubuntu 12.10
	. ubuntu 14.04 (build machine)

. Tests on OS-X show the statically linked Mac exes are reasonably compatible.  However, a user should be able now to recompile on a standard configuration Mac using script ocmplls.sh, assuming of course that GNU/Ada is installed.

. added cartoon palm tree, level 1;
. using better illusion for exit box;
. revised build scripts, instructions;

........................ 3.1 27feb15 ............................................
. CRITICAL correction fixes abort when reading level 4 puzzle data;
. added wall scenes with dynamic content;
. added SDL-version queries & reports;

........................ 3.0 15jan15 ............................................
. corrected a typo-error that produced a bad portal exit height;
. lumber(lambda) & brick(beta) levels now begin on top of ledge for better view;
. revised 4th DoD puzzles for uniformity and playability; added 5th DoD;
. added instructions for user replacement of puzzles: puzzle_replacement.txt.
  Note, there are hardcoded limits on #rows, #cols, #barrels.
  Thus, more asserts to flag puzzle limit violations were added.
. ZPMs and receptacles now glow when activated.

........................ 2.9 11jan15 ............................................
. elliminated need for command-line parameter;
. corrected a geometrical error in DHD pick function;
. now using hand for DHD selector; 
. improved look of DHD, stone return door;
. initial DoD=1;  each game completion increments default DoD;
. sokoban walls now match each room's building material;
. using new music & thatched roof for adobe tomb;
. generally more coherent & smooth gameplay;

........................ 2.8 07jan15 ............................................
. updated level 5 skybox for a more spectacular epilog;
. corrected prolog/epilog shader derivatives (no visible improvement);
. increased wave amplitude and added wave peak foam in prolog;
. portals are now hollow/empty until activated;
. the former prolog is now a nexus-hub for all 4 dungeons, where users can
  set the Dial-Home-Device [DHD] to choose their destination;
. each return to the island has distinct skybox.

........................ 2.7 29dec14 ............................................
. improved surfline foam to include position-based-phasing
  of foam ebb/flow (unrelated to water-wave ebb/flow);
. added greenish tint to shallow ocean;
. corrected a reflection error in the ocean shader;
. updated island skybox, making the [reflective-]ocean more beautiful;

........................ 2.6 23dec14 ............................................
enhancements to prolog:
. ocean opacity now a function of depth;
. added surfline foam;
. added tell tale jar of ointment;
. improved grasses, tall palm;

....................... 2.5 17dec14 ................................................
. revised sok puzzle definitions:  one file per degree of difficulty [DoD];
  Now with 5 DoDs (1=>easy, 5=>hard);
. added fish, shark and more foliage in prolog;  improved foliage texture behavior;
. frame for stargate;
. bumped up water/island resolution;  still good on older macbooks, slightly
  noticeable jitter on Retinas, but no more than level 2.

....................... 2.4 10dec14 ................................................
. discarded use of GLFW3 in favor of SDL2 because of a thin binding made available by
  Dan Vazquez <danva994@student.liu.se>;  see https://github.com/danva994/AdaSDL2
. Now, after this conversion to SDL2, highDPI works again even under Yosemite!
. improved water reflections in prolog;  now the sky is more accurately reflected
  in the water with respect to a changing viewpoint;

.......................... 2.3 04dec14 ................................................
. discovered yosemite somehow prevents Ada from achieving highDPI (cpp is Ok);
. advise to Maverick people using Ada:  do NOT upgrade yet to yosemite!
. greatly reduced coding complexity and graphical burden for several textured objects;
  this now allows OSX binaries to run smoothly on older Macs.
. improved appearance of Electra, starfish, crab;
. corrected island waves so they don't follow the viewpoint;
. genericized several objects to simplify code;
. raised water level in epilog so it looks better;
. improved level 2 reflective water;

.......................... 2.2 26nov14 ................................................
. updated build scripts;  OSX-yosemite needed a workaround for GNAT to function;
. added gl_mirrored_repeat setting to libs/gl/gl.ads;
. significantly improved textures, especially sand;

.......................... 2.1 18nov14 ................................
. added artifacts of an ancient mystery;  and a salute to an American heroine (level 0);
. improved level 0 skybox;

............................ 2.0 13nov14 .......................................
. improved sound system to handle 2 simultaneous sound loops in addition to other transient sounds;  eg. we now can hear music & water & portal guns;
. added auditory cues to signal ZPM solution and wormhole activation;
. made corrections to sound logic;  eg. wormhole hum quits if ZPM is knocked off of its receptacle;
. improved compilation scripts;

........................... 1.9 10nov14 ..........................................
. added kick sound;
. improved panning action using mouse or pad;
. prevented getting stuck near walls or ledges;

........................... 1.8 6nov14 ..........................................
. improved puzzle data structures to allow easy reconfiguring;
. inserted new puzzles with higher maze-like walls;  jump to enter;
. added user control of puzzle difficulty with optional command-line parm:
	1=easy, 2=default, 3=hard;

..........................1.71 4nov14 ............................................
. updated OSX binary with statically-linked SFML 
  (so target Macs don't need SFML just to run AdaGate)

............................. 3nov14 ........................................
. This update no longer requires mplayer, but uses instead a 
  very limited Ada interface to a few SFML-AUDIO functions.

..................... 30oct14 ...................................
. improved ZPM-barrel movement code;
. cleaned up libraries and added gnu-gpl statements where missing;
. equilibrated keyboard slew speed for computationally intensive fragment shaders;

.................................................
. revised/restored background music that ends when wormhole becomes active;
. cleaned code, improved robustness;

........... sep14 ..................................................
. both GNU/Linux and Mac OS-X binary executables included:
  adagate_osx, adagate_gnu;
. added level 5 epilog;
. reflective water in levels 2, 5;
. added GNU GPL statement to sources;
. code corrections/improvements;
. now allow key-left/key-right [in addition to mouse] rotations in epilog;
. added level 0 prolog;
. various corrections and improvements;



==========================================
what is special about this project?
==========================================
Uses fully modern OpenGL methods in Ada with textures, shaders and uniforms, achieves version 3.3 core profile contexts, and compiles and runs on both GNU/Linux and Mac OS-X systems.  This project serves as a testbed for learning the complexities of modern OpenGL and GLSL.

Focusing on portability, no coding effort or compromises have been made to accomodate proprietary operating systems.  It relies on a thin SDL2 binding from Dan Vazquez, a thin OpenGL binding from "Lumen", a PNG reader by Stephen Sanguine, and SFML-Audio (because of its elegant audio interface).

If one defines "modern" OpenGL to mean version 3.3 or higher, then this may be the most functionally advanced demonstration of "modern" OpenGL using Ada to be found.  Written in C++ style, the code is not elegant and neglects some safety features available to Ada, but it does serve as a working example that focuses on learning OpenGL.  The Ada bindings used are thin, so the relationship to C++ methodology is quite transparent.  Developers should note that these Ada bindings are usable as a standalone library for most any OpenGL project that uses Ada.

Thus, for the C++ programmer this app should be easy to comprehend; and for the experienced Ada programmer there are many potential improvements to be made.  Suggestions or improvements from Ada developers are not only welcomed, but solicited.


------------------- explanatory note on SFML versus SDL2 -----------------------
I tried using SFML rather than SDL2 for my windows and event loop management, but I discovered that SFML does NOT currently allow the core or forward compatible settings that are required to use OpenGL v3.3 on OS-X.  This article:

http://www.glfw.org/faq.html#how-do-i-create-an-opengl-30-context

explains that, indeed, OSX only supports forward-compat, core profiles.  It seems that SFML still uses some OGL-deprecated functions (which preclude forward-compat).  On the other hand I did not use SDL2 audio because SFML audio seemed simpler and more powerful.  In fact, I am planning to replace SDL2 with SFML when I see an SFML update that allows the forward-compatible setting needed to support OSX.  I was told that the ellimination of OGL-deprecated functions from SFML was planned but is low on the priority list.


==============================================================
AdaGate Game Description
==============================================================
AdaGate is a first-person 3D sokoban puzzle game within a Stargate / Portal fantasy setting. It is a great example of modern OpenGL programming using the Ada language. 

While exploring a remote south-seas island an operational stargate lures you into 4 strange dungeons. Escape will require the logical rearrangement of weird power cells [ZPMs] that roll in only two directions. Shoot your portal guns at the dungeon walls to configure 2 escape portals, but in order to activate them, all of the ZPMs must be bumped onto their sockets. But beware: you can only PUSH the ZPMs, so you will fail if you roll one into a corner or against a wall. But don't worry, cheating is pretty easy ; )

With 5 degrees of difficulty [DoD], there are 20 user-replaceable puzzles to solve. Escape all 4 dungeons to access the neptune choir epilog and increment the DoD for your next adventure.



======================================================================
AdaGate Game Features
======================================================================
Works on PCs or laptops running OS-X or GNU/Linux.  And if GNAT is installed you can build it yourself!  But first try the delivered binaries.

Both GNU/Linux and OS-X binaries provided, as well as full source. Improved compatibility of pre-built binaries run on many recent distros of linux and OS-X.

Supports high DPI mode on Mac Retina displays.

Laptop friendly controls; Also runs on older hardware.

A first-person (you are the pusher) 3D Sokoban puzzle game that uses the intersection of two cylinders as a puzzle piece that rolls in two perpendicular directions.

New stargate dial-home-device [DHD] allows non-linear play; watch island setting evolve.

Roll the cylindrical ZPMs to empower the portals and escape thru a wormhole

Four rooms and five degrees of difficulty for a total of 20 challenging puzzles. And now solutions are available in the file ./data/solns.sok.

Serves as a blueprint for modern OpenGL programming in Ada or C++ using GLSL 330 and shaders.

Note that the Ada bindings to OpenGL & SDL2 in this app are usable as a standalone library for most any modern Ada project.

See also: WorldCupSokerban, a 3rd-person 3D sokoban game within a soccer field. Comes with an autosolver!


--------------------------------------------------------------------------------
---------------------------------begin short intro------------------------------
AdaGate is a first-person 3D sokoban puzzle game, embedded into a stargate fantasy setting.  It uses the intersection of two cylinders as a puzzle piece, that rolls in two perpendicular directions.  AdaGate demonstrates modern OpenGL programming using the Ada language.

Works on Macs running OS-X and PCs running GNU/Linux.

-----------------------------------------------------------
-- controls
-----------------------------------------------------------
Look direction is controlled by touch pad or mouse;

Movement is controlled by the arrow keys:
   <Up>
<Lt>	<Dn>	<Rt>

Shoot the two portal guns using:
"L"-key, "R"-key, 
or  
Left-Mouse, Right-Mouse

<space> = jump up/over short walls

<esc> = exit;  

To begin, open a [command-line] console, and at the command line type "adagate_gnu" or "adagate_osx".  If you ever get stuck, try to jump up & forward.

------------------------------------------------------------



required for running:
-------------------------------------------
. graphics card & driver that supports OpenGL version 3.3 or later;
. GNU/Linux or a Mac running OS-X (even Yosemite);
. adagate_gnu is the executable name on GNU/Linux.
. adagate_osx is the executable for Mac OS-X.


Open Source libraries required for building:
-------------------------------------------
. systems:  OS-X or GNU/Linux
. a recent gnat compiler
. the included "libs" directory contains Ada interfaces;
. see example scripts;
. Note that the Ada interface to SFML-AUDIO (snd4ada_hpp.ads) was created with the command:
  "g++ -c -fdump-ada-spec -C snd4ada.hpp"
  which references a minimalistic C++ utility snd4ada.


Running adagate:
-------------------------------------------
Unzip the archive and you will see a new directory appear with a name like "bundle_<date>", that you should rename to something like "adagate_install_directory".  

Linux users should then cd to adagate_install_directory, then type "adagate_gnu" to start the game.  In case of an annoying system popup asking to either a) ForceQuit or b) Wait, simply hit the return key to select "wait" because AdaGate is slow to load.  (I read online that that is a quirk of Gnome, but I'm not sure about that.)

Mac users please note:  this game is initiated by opening a terminal, navigating to the adagate_install_directory, and typing "adagate_osx" on the command line.

The adagate_install_directory should contain a subdirectory named "data".  It contains shaders, skyboxes, sound and texture data, as well as the puzzle definitions.

An optional command line parameter of 1..5 will choose the Degree-of-Difficulty [DOD], but it is normally unnecessary since the DoD increments itself after each game.  If you succeed at DoD= 3 or 4 then you are ready to try WorldCupSokerban or RufaSok!

By the way, you are ideally supposed to solve the sokoban puzzles without jumping back onto the walls.  If you do, it might be said that you cheated!  Conversely, if you jump into the puzzle at the wrong place, it might be impossible to solve.

======================================================================
Open source Ada developers are welcome to help improve or extend this game.

Developer or not, send comments, suggestions or questions to:

<fastrgv@gmail.com>


===========================================================================
===========================================================================

Build instructions for AdaGate:

Two [pre-compiled] binary executables are provided, one for gnu/linux and one for OS-X.  The linux binary, adagate_gnu, is intended to run in the presence of the directory "libs", which contains some dynamically loaded libraries that can be, but need not be present on a target system:  SFML, SDL2

No Makefile is provided, but build scripts are offered.  Suggestions for improving the build process are welcome.

-------------------------------------------------------
MacOSX:

ocmplls.sh:  build script for generating a portable executable that will run on most OS-X platforms whether or not they have non-standard libraries SDL2 or SFML installed.  I used this to build the executable that I deliver, named adagate_osx.  Macs with a recent but standard configuration of OS-X should be able to rebuild using this script.

------------------------------------------------------
GNU/Linux:  

lcmplld_ag.sh:  utilizes the uncommon relocatable libraries (mainly SDL2, SFML) that are delivered in this bundle under ./libs/.  This is used to build the dynamic [gnu/linux] executable, which should run in the presence of ./libs, whether or not your system has those libraries installed.  This was used to create the executable named adagate_gnu.  Using "linux app checker" this executable should run on:
	. fedora 15-18
	. opensuse 12.1, 12.2
	. ubuntu 12.10 and presumably 14.04 (the build machine)

If it doesn't run on your linux distro, you will have to try to build the executable yourself.  In that case, it is hoped that this script (lcmplld_ag.sh) will work for you.  The intent was to provide all the needed interface/include files under ./libs/.






==============================================================================
============ legal mumbo jumbo: ==============================================
==============================================================================


AdaGate itself is covered by the GNU GPL v3 as indicated in the sources:

--
-- Copyright (C) 2015  <fastrgv@gmail.com>
--
-- This program is free software: you can redistribute it and/or modify
-- it under the terms of the GNU General Public License as published by
-- the Free Software Foundation, either version 3 of the License, or
-- (at your option) any later version.
--
-- This program is distributed in the hope that it will be useful,
-- but WITHOUT ANY WARRANTY; without even the implied warranty of
-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-- GNU General Public License for more details.
--
-- You may read the full text of the GNU General Public License
-- at <http://www.gnu.org/licenses/>.
--
========================================================================
Media Files for AdaGate:


General Note
============
The particular choices of sound, image, and shader files (*.fs) delivered are not essential to the function of the game and are easily replaced.  This software is primarily intended as a tutorial example of modern OpenGL methods using GLSL.  The only requirements are that sounds be in WAV format, images be in PNG format, and shaders be updated to GLSL 330 specifications.  Skybox images have an additional constraint, they must also have a 90x90 degree field of view [for a correct perspective], and all 6 must have the same pixel dimensions.

Defining Your Own Puzzles
==========================
Read: puzzle_replacement.txt

SoundFiles (*.wav)
===========
Most are from freesound.org and are covered by the Creative Commons Attribution noncommercial license documented in the accompanying file ccnc3_license.txt.  see also:  http://creativecommons.org/licenses/by-nc/3.0/legalcode/

"Among the Falls" [music for level 1] is from http://www.freesfx.co.uk.  See the file "freeSFX_license.txt.


ImageFiles 
==========
Most images for textures were freely [no copyright indications] available on google images.  Some wall textures used are from the GPL2.0/GPL3.0-only section of OpenGameArt.Org.  One other thatched roof texture was used from http://www.mayang.com/textures.  See mayang_license.txt.


ShaderFiles 
===========
Some fragment shader files used were downloaded from http://glslsandbox.com/ and put under ./data/ that are not labelled as GNU-GPL'd, namely:

clouds.fs, darkwater3.fs, starfield3.fs, volcano.fs
...as well as some sections of a couple of other fragment shaders...

...these appear to contain comments from their authors so were left unchanged.  However, most fragshaders from glslsandbox are under the MIT license (see mit_license.txt).

Also from glslsandbox...added:  "Red Planet" from Mahmud Yuldashev <mahmud9935@gmail.com> as well as the following uncredited:
. blueSpiral.fs
. redPlanet.fs
. cloudyPlanet.fs
. mountainScape.fs
as well as the CreativeCommons licensed:
. waterWorldCCNCSA3.fs
which seems to be credited to Alexander Alekseev with mods by Mahmud Yuldashev.

As with most, I had to modify to glsl version 330 and adapt them to use some programatic uniforms for input.



SkyBoxes 
========
For some of these, I had to lower the horizon slightly for technical reasons;  and for others I converted to *.png files with RGBA mode.

One used is from www.custommapmakers.org/skyboxes.php, which gathers together many free-to-use skyboxes.

Another skybox  [from  http://www.redsorceress.com/skybox.html]  is credited to "The Mighty Pete" at http://www.petesoasis.com (which seems defunct).

Another one used [from OpenGameArt.org] is the work of Heiko Irrgang <hi@93-interactive.com> and is licensed under the Creative Commons Attribution-ShareAlike 3.0 Unported License.  To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/3.0/ or send a letter to Creative Commons, 444 Castro Street, Suite 900, Mountain View, California, 94041, USA.  See also the accompanying file ccsa3_license.txt.

=================================================================
video links:

new [rg] prolog:
http://youtu.be/7vdZ1PPTPjw 

level beta puzzle:
http://youtu.be/WQU5kdO_93k

level beta lava pit:
http://youtu.be/0LH9H0hNF1Q


A 3rd party 11 minute video of AdaGate is here:
https://www.youtube.com/watch?v=qNPc6yXfIV4&feature=youtu.be