Start ProgrammingΒΆ

HGamer3D comes pre-build with a set of tools, to use it easily. So before you try to compile everything yourself - this is explained in a later section (somewhere in the future) - at least give the following short starting guide a try.

The single steps to create a running game from a source template for all three platforms (Windows, Mac, Linux) are as follows: first you need to download a small toolset and install it in a directory of your choice. Then you need to start a command line interpreter (cmd.exe, bash) with access to git and source the path of the toolset by calling a specific batch file. After that you can initialize the tooling and finally you are ready to scaffold a template project, compile and run it.

The time to do all that is about 10 minutes.

Create Tool Directory

Please create a new directory either in the explorer of your OS or with the command line. Then download the toolset for your specific platform from one the following links:

Finally extract the content of the downloaded archive there. The content of your directory should be a single set-path batch file and a tools directory. Note the path to the the set-path batch file, you will need to call this one in the next step.

Run command line interpreter and modify PATH

During creation of the HGamer3D template project and the compilation of its source you will work in a command line interpreter. Usually this is cmd.exe on Windows and bash on Linux or Mac. You will work in a different directory than the one where you extracted the tools. All you need to do to make the tools available is to source the set-path script like so:

source <PATH TO TOOLS>/set-path

In Windows you can ommit the source command. With that you added the tools directory to your path and you can start to initialize the toolset.

Initialize Tools

There is one command, which you only need to call once per user, to setup the toolset. Specifically what this command does is it links some generic commands to more specific ones by setting alias commands. In addition it installs the Haskell toolchain for the used version of GHC. Call the following command from your command line interpreter.

initial-setup

This might take a while and will involve downloading a set of tools and initializing Stack and GHC. If you want to remove the downloaded things later, everything downloaded is located in ~/.aio, so no trouble in removing it later.

Scaffold, Build and Run Project

Now everything is ready to go, you can create a new project directory with create, build the created program with build and run it with run game.

create GameProject
build
run ./game

Done.


_images/RotatingCube2.jpg

Examining the Code

If you want to have a first preview into a functioning code snippet fire up the editor and have a look at the code with aio Edit game.hs.

Do you recognize the typical Haskell program structure? The Main module declaration and imports at the beginning, a function called gameLogic and one called main? Try to modify this code in the editor, for example, change the color to green, re-compile the code with build and run it with run.

{-# LANGUAGE OverloadedStrings #-}

module Main where

import HGamer3D
import Control.Concurrent
import Control.Monad

gameLogic hg3d = do

      es <- newET hg3d [
            -- create camera
            () -: [
                  ctCamera #: FullViewCamera,
                  ctPosition #: Vec3 1 1 (-30.0),
                  ctLight #: Light PointLight 1.0 1000.0 1.0 
                  ],
            -- create text
            () -: [
                  ctStaticText #: "Rotating Cube Example",
                  ctScreenRect #: ScreenRect 10 10 100 25
                  ],
            -- create geometry, with child geometry items
            "eGeo" <| ([
                  ctGeometry #: ShapeGeometry Cube,
                  ctMaterial #: matBlue,
                  ctScale #: Vec3 5.0 5.0 5.0,
                  ctPosition #: Vec3 0.0 0.0 0.0,
                  ctOrientation #: unitU
                  ], [
                        "eSmall" <| ([
                              ctGeometry #: ShapeGeometry Sphere,
                              ctMaterial #: matGreen,
                              ctPosition #: Vec3 (-0.5) 0.5 (-0.5),
                              ctScale #: Vec3 0.8 0.8 0.8,
                              ctOrientation #: unitU
                              ],
                              [
                                () -: [
                                    ctGeometry #: ShapeGeometry Sphere,
                                    ctMaterial #: matRed,
                                    ctScale #: Vec3 0.5 0.5 0.5,
                                    ctPosition #: Vec3 (0.0) (-0.5) (-0.5),
                                    ctOrientation #: unitU
                                    ]
                              ])
                  ]),

-- HGamer3D website, entities and events, example exit button with callback
            -- create button
            "eButton" <: [
                  ctButton #: Button False "Exit",
                  ctScreenRect #: ScreenRect 200 10 50 25
                  ]

            ]

      registerCallback hg3d (es # "eButton") ctButton (\(Button flag _) -> if not flag then exitHG3D hg3d else return ())
-- end of website text

      -- rotate the cube
      let rotate = do
            forever $ do 
                  updateC (es # "eGeo") ctOrientation (\u -> (rotU vec3X 0.0013) .*. u)
                  updateC (es # "eGeo") ctOrientation (\u -> (rotU vec3Y 0.005) .*. u)
                  updateC (es # "eSmall") ctOrientation (\u -> (rotU (Vec3 (-1.0) 1.0 (-1.0)) 0.05) .*. u)
                  sleepFor (msecT 20)
            return ()

      forkIO $ rotate

      return ()

main = do 
      runGame standardGraphics3DConfig gameLogic (msecT 20)
      return ()