readme.html

# Open Sonic

Open Sonic is a free open-source game based on the "Sonic the Hedgehog" universe. It introduces a different style of gameplay called cooperative play, in which it's possible to control 3 characters simultaneously. Unlike most similar games, Open Sonic provides a greater level of interaction between the player and the levels. It's more than just a jump'n'run; the user must come up with some strategy in order to get through the levels.

Currently this game works on Windows, Linux and Mac OS X.

This game is not endorsed, produced or affiliated with Sega, or any of its subsidiaries. Sega did not make this. This is a non-profit unofficial fangame based on the "Sonic" universe and should be categorized under the same criteria as fanart or fanfiction. The creators of this game are not liable for any and all damages you incur while playing. Sonic, Tails, Knuckles, Eggman, and all related characters, objects and locations are property of their respective owners. All other copyrighted characters contained within belong to their own respective companies and organizations.

## How to play

### How to execute the game

To start the game, run the opensonic executable.

### Menu options

- Start Game: starts the regular 1-player mode game;
- Tutorial: starts the Tutorial, a quest where one can learn-by-doing how to play the game;
- Extras: one can play on custom levels too! Basically a quest is a sequence of levels;
- Options: configures the game;
- Exit: quits the game.

### Moving the characters

You can play using your keyboard or a joystick. If you decide to use a joystick, make sure it has at least 2 axis and 4 buttons. Plug it before you start the game! If you want to play using your keyboard, see the table below to know how you can control the characters at any level:

Key | Effect
--- | ---
Arrow keys | Move
Space bar | Jump
ENTER | Pause
Left CTRL key | Change the active team member
ESC | Quit
PrintScreen or '=' | Snapshot
F6 | Ignore/restore joystick input

### Cooperative play

Cooperative play is an exciting feature of the game which allows you to control 3 characters simultaneously! Each character has unique advantages and disadvantages, so some team work is needed in order to get through the levels.

To learn more about cooperative play, please play the Tutorial.

## Level Editor

When you're playing at any level, press F12 to access the level editor. There are 3 edit modes: brick mode, item mode and enemy mode. Basically a brick is a background object or a platform; an item is something like a ring, a life box or a checkpoint; and it's obvious what an enemy is. In the following table, an 'object' may be a brick, an item or an enemy, depending on the current edit mode.

Our website contains detailed level editor tutorials.

Key | Effect
--- | ---
F12 | Quit
Arrow keys or W,A,S,D | Move the camera
Ctrl+Arrow keys or Ctrl+W,A,S,D | Move the camera (faster)
B / N or Mouse wheel | Previous/next object
Ctrl+B / Ctrl+N or Ctrl+Mouse wheel | Previous/next edit mode
Left mouse button | Create an object
Middle mouse button or P | Pick an object
Right mouse button | Delete an object
Ctrl + left mouse button | Change the spawn point
Ctrl+Z / Ctrl+Y | Undo/Redo
G | Enable/disable grid

Tip #0: use the left control key.
Tip #1: press Ctrl+F12 to save the level with your modifications. This operation is irreversible! If you want to modify a level permanently, we urge you to backup the level/ folder! Under Linux, if you have no write privileges on the GAME_DIRECTORY/levels/ folder, the game will save it on $HOME/.opensonic/levels instead.
Tip #2: if you want to make your own levels, you should read the level editor tutorials at our website.
Tip #3: in order to pick up (or delete) an item, you must select the item mode. Similarly, in order to pick up (or delete) a brick, you must select the brick mode. Same about the enemies. Use Ctrl+N or Ctrl+B to change the edit mode.

## Troubleshooting

Our website contains an updated FAQ area.

## Advanced features

### Command line options

This game provides several features via command line. Open a terminal and type:

    opensonic --help

### Game resources

Linux users: since version 0.1.1, you can store custom levels, quests, images, sounds and so on in GAME_DIRECTORY/ (default) and also in $HOME/.opensonic/ . GAME_DIRECTORY is the directory where you installed the game. In other words, if the game is located in some folder which you don't have write privileges, you can, for example, make your own levels with the level editor and save them in the $HOME/.opensonic/levels/ folder.

## How to compile

### Overview

To compile the game you need a C-language compiler and the programming libraries that this project uses. You also need CMake, a cross-platform open-source build system.

Let's define GAMEDIR as the directory where you unpacked the game. GAMEDIR stores, among other things, this readme.html page and a file called CMakeLists.txt

### Obtaining the libraries

Once your compiler is working properly, you'll need to install the following free programming libraries:

- Allegro 4.4.1.x, with (at least) the following addons:
  - JPGalleg
  - loadpng - requires: zlib and libpng
  - LOGG - requires: libogg and libvorbis

In a regular installation of Allegro 4.4, JPGalleg and loadpng and LOGG are already included by default.

I won't get into details on how to install these libraries. Please check out their respective websites to know the detailed instructions.

Note: you can disable the DUMB library by uncommenting the SET(DISABLE_DUMB TRUE) line in CMakeLists.txt. Similarly, you can also disable the .ogg support by uncommenting the SET(DISABLE_LOGG TRUE) line in the same file. However, we do NOT recommend disabling these resources, since they are required for music playback.

### Compiling on GNU/Linux - gcc

Open a terminal, go to GAMEDIR and run the following commands:

    chmod +x configure
    ./configure
    make
    sudo make install

To launch the game, type:

    opensonic

Note: if you find errors about the "allegro-config" script, it's recommended that you compile Allegro from the source code yourself.

### Compiling on MS Windows - MinGW

If you use MingW, make sure both lib\ and bin\ folders are listed on your PATH. If MinGW is installed on C:\MinGW\, you can use the command

    set PATH=%PATH%;C:\MinGW\bin;C:\MinGW\lib

(on the Command Prompt) to achieve that goal.

On the same Command Prompt, please go to GAMEDIR and run the following commands:

    cmake -G "MinGW Makefiles" .
    mingw32-make

Note that little '.' at the end of the first command. If everything worked well, opensonic.exe should be in the GAMEDIR folder.

### Compiling on MS Windows - Microsoft Visual C++

In this example I'm using Microsoft Visual C++ 2008 Express. A similar approach should work on different versions of MSVC. On my computer, this software is installed at C:\Program Files\Microsoft Visual Studio 9.0\VC\. Make sure the lib\ folder is listed on your PATH. If you're not sure, on a Command Prompt, run

    set PATH=%PATH%;C:\Program Files\Microsoft Visual Studio 9.0\VC\lib

On the same Command Prompt, please go to GAMEDIR and type:

    cmake -G "Visual Studio 9 2008" .

Now a Microsoft Visual Studio Solution file should be located on GAMEDIR. Open it, select Release as the Active Configuration and compile. After that you should see opensonic.exe inside the GAMEDIR\Release folder. Copy it to GAMEDIR.

On different versions of MSVC, you must change the "Visual Studio 9 2008" argument when you run cmake. Type

    cmake --help

on a Command Prompt for more information.

Our wiki contains more detailed tutorials on this subject.

### Compiling on Mac OS X

Mac OS X support is experimental. Please read the Compiling on GNU/Linux area (see above) to know how to compile the game. The instructions are the same.

### Other compilers/other IDEs

If you want to compile this game using other software, please run

    cmake --help

on a terminal for more information. Using CMake, it's possible to generate the data needed for other compilers. CMake can also generate project files for other popular IDEs like Code::Blocks, KDevelop, etc. For example, under Linux, in order to generate a Code::Blocks project (opensonic.cbp), you may run

    ./configure -G "CodeBlocks - Unix Makefiles"

## Credits

### License

The code of this game is licensed under the GPL version 2. Please read the file license.txt that comes with this software.

### About this game

Open Sonic is written from the ground up in C language and uses the Allegro game programming library for graphics, sounds, player input and timers. It also uses the DUMB and LOGG libraries for music playback, loadpng and JPGalleg for image loading/saving routines and lib2xSaI for improved graphic rendering. This game was originally written by Alexandre Martins, a computer science student from Brazil, and now it has several contributors all over the world! Game development is a such a beautiful and fascinating area, and one can learn a lot while making a game! That's why we love it so much.

This game is still in development. Currently it uses mostly "ripped" graphics and sound effects, but we're step-by-step replacing those resources by original user-made content. This game is developed by volunteers. We need your help! You can help this project in many areas: art, sounds, levels, etc. Please take a look at our wiki to know exactly how you can help.

Thank you for reading. :)