From Spheriki

Contents 1 Introduction 2 Why Use Sphere 2 3 The Engine 3.1 Directory Structure 3.2 Engine Configuration 3.3 Engine Execution 4 Writing A Game 4.1 Defining The Entry Point 4.2 The Game Loop

Introduction

Sphere 2 is the unofficial successor to the original Sphere game engine written by Chad Austin. It's an attempt to modernize and extend the Sphere engine while trying to keep its principles.

The goals of Sphere 2 can be summarized as follows:

• Be simple.
• Be easy for beginners and powerful enough for advanced users.
• Be flexible.
• Be extensible.
• Be platform independent.
• Provide a rich set of standard functionality and authoring tools.

Of course, some of the goals can't be achieved without affecting another one, so Sphere 2 tries to maintain a balance between each one of them.

Why Use Sphere 2

Sphere 2 is a high-level abstraction layer which offers a wide range of functionality designed for game development. It comes with a rich set of standard systems and authoring tools to aid in the development process.

Sphere 2 abstracts

• Handling memory
• Accessing the filesystem
• Handling the game window
• Handling user input
• Handling resources like images and sounds
• Rendering graphics
• Playing sounds
• etc.

In Sphere 2 you don't need to deal with memory management, platform differences and their underlying API's, third-party libraries, compilers, etc. Those are all handled by Sphere 2, so you can concentrate on your game. Write your game once in a powerful scripting language and using a consistent API and the game will work out of the box on any platform Sphere 2 supports. No need to alter your game content, no need to recompile it for a specific machine.

The Engine

This chapter explains some of the engine concepts.

Directory Structure

There are three directories the engine keeps track of:

• The directory containing the engine runtime files (for example the engine executable, libraries, addons, etc.), called engine.
• The directory containing the game data (for example scripts, images, sounds, maps, etc.), called data.
• The directory containing system resources and any files shared across games, called common.

The data and the common directories usually reside in the engine directory, but they don't have to, i.e. you can have an installment like this (assuming Windows):

• The engine directory as C:\Programs\Sphere
• The data directory as C:\Programs\Sphere\data
• The common directory as C:\Programs\Sphere\common

or like this:

• The engine directory as C:\Programs\Sphere
• The data directory as C:\Programs\MyGame
• The common directory as C:\Shared Files\Sphere

That's because in case you don't have permission to write in the engine directory, you can put the data and the common directories in a different place and leave the engine directory where it is. Or in case you just want them to be in different locations, for whatever reason.

Sphere's standard filesystem restricts any file access to these directories and you need always to put the name of the "root" directory in front of the file path. For example, the correct filename to open a file named foo/bar.txt in the common directory would be /common/foo/bar.txt.

Engine Configuration

On start-up the engine reads the configuration from /engine/engine.cfg. This is a simple INI file with a section named Engine and the following keys:

• CommonPath: Defines the common directory. Default is /engine/common/.
• DataPath: Defines the data directory. Default is /engine/data/.
• MainScript: Defines the script to be run on start-up. The script must contain a function called main which will serve as the game's entry point. Default is game.

You can set the keys to any values you like, if a key is not present or has no value, the engine will use the default.

This configuration can be overridden by command line arguments (see below).

Engine Execution

When the engine is executed it initializes its state, processes the command line options, looks for the main script, if found evaluates it and calls its main function with all the -arg arguments.

The engine accepts the following command line arguments:

• -common <path>: Defines the common directory.
• -data <path>: Defines the data directory. If path is relative (for example mygame), it is considered to be relative to the engine directory, i.e. the command line argument -data mygame would result in the data directory /engine/data/mygame. This allows for multiple games installed in /engine/data.
• -main <filename>: Defines the script to be run on start-up. filename is a file path relative to the data directory, not including the file extension. The script must contain a function called main which will serve as the game's entry point.
• -arg <argument>: Defines an arbitrary argument to be passed to the main function. Any number of -arg's is allowed, since the main function expects a variable size argument array. The arguments will be passed to the main function in the same order they appear on the command line.

The engine logs any output to /engine/engine.log.

Writing A Game

In Sphere 2 a game at least consists of a main script which defines the game's entry point function main. In addition a game might include auditive content like background music and sounds, visual content like images and sprites and additional scripts which implement the game's data structures like maps and control the program flow.

Sphere 2 uses the Squirrel programming language for scripting. See Squirrel Programming Language for further information.

Defining The Entry Point

The main script must define a function called main as follows:

function main(...)
{
  // stuff
}

This function serves as the game's entry point and will be called by the engine upon evaluation of the main script. Any game parameters passed to the engine will be passed to the main function in the same order they appear on the command line. They will be accessible through the vargv array (see Squirrel Programming Language for further information).

The Game Loop

The game loop is the central element of a game and makes sure the game runs smoothly regardless of any user input. It processes the user input, updates the game state, plays sounds, draws graphics and outputs the result as the next frame in the game window.

Usually the game loop is implemented as a simple while loop that iterates as long as the user doesn't exit:

while (user doesn't exit)
  process user input
  update game state
  play sounds
  draw graphics
  show result in the game window