Introduction to Arc

by Clay Smith (clayasaurus)

Preamble

I am Clay Smith (clayasaurus) and I wrote Arc as a 2D Game Arcade Library so I would have a solid base to build my games upon, and as a way to empower newbies and D lover's to make fun 2D games. Arc is an API that’s higher than OpenGL but lower than a complete game engine. It supports FreeType fonts, sprites with 3 different collision types (radius, box, and perpixel), particle effects, simple input and windowing, sound effects, and more. Arc is mostly licensed under zlib-png and will be 100% zlib in the near future, the only other license included is LGPL.

This tutorial will teach you how to set up your D compiler environment on Windows and compile a simple 'Hello World' test application. Once you get this working, I will give you a brief overview of major features in Arc v.01.

Setting up the D compiler environment

1. Download and install D compiler

2. Installing and Setting up a Poseidon project

Poseidon is a nice D development environment for Windows that we will use in this tutorial.

Once Poseidon is installed, open it up and go to 'file->New Project.' Choose project name and create a new directory which you wish to store your project and hit 'Ok.' Make sure your directory path doesn't have any spaces such as 'C:\Desktop\My Project,' as the D compiler may have problems in dealing with spaces.

3. Testing your shiny new D compiler.

In the Poseidon 'package explorer,' you will see a folder with your project name. Right click on it and select the option 'New,' then select 'File.' This will add a file to your project. Name the file 'main.d', and add the following source code...

[Get Code]
module main;

import std.stdio;

int main()
{
   writefln("Hello D World!");
   return 0;
}

Now, to test your code we are going to create a batch file that will build your program and pause, run your program and pause. The pausing helps you view compiler errors and allows you to see what your program prints before closing. Make sure you create this file with the command line 'edit,' or perhaps another pure text editor will work.

To use 'edit', go to Start->Run and type 'cmd' in the dialog box, then use 'cd C:\yourdirectory' to go to your directory, and type 'edit' to start the Microsoft prompt text editor. Type in the following code and save the file as 'run-build.bat'.

[Get Code]
build main.d -Rn
PAUSE
main
PAUSE

Now in Poseidon, click on the 'green arrow and brown suitcase' button, this will call your batch file and after each pause hit 'enter.' You will eventually see your programs output. Now that you can compile simple D programs, you are ready to start playing with Arc!

Setting up Arc

1. Setting it up.

Download Arc v.01 from here. Extract the contents into your project folder. This file contains all the source code and binaries necessary to get Arc running. You will now notice an 'arc' folder and a series of DLL's used by Arc, and you will also notice a 'derelict' folder, this is the version of derelict that was used with the given version of Arc.

2. Hello World.

Refresh your project by right clicking on the project folder in the 'package explorer' and hitting 'refresh.' Then enter the given source code into 'main.d'.

[Get Code]
module main;

// include input, window, and font to display 'hello world'
import arc.io.input,
         arc.io.window,
         arc.gfx.font;

int main()
{
    // Open window with title, screen width, height, and bits per pixel
    arc.io.window.open("Hello World", 400,300,0);

    // Open input handling
    arc.io.input.open();

    // Create a new font with height of 32
    Font font = new Font("test.ttf", 32);

    // while the user doesn't press the SDL_QUIT button
    while (!arc.io.input.keyDown(SDL_QUIT))
    {
        // process input
        arc.io.input.process();

        // clear the current screen
        arc.io.window.clear();

        // draw the font in the center of the screen
        font.draw("Hello Arc World", 200,200,0,255,0,255);

        // swap window buffers
        arc.io.window.swap();
    }

    // clean ourselves up and exit
    arc.io.window.close();

    return( 0 );
}

Compile and run this code and you should get a window that pops up that says 'Hello Arc World.'

2. Brief overview of major Arc features

Now that you already have a taste of Arc and know how to set up the compiler environment and IDE, we can move into more detail on Arc itself. First, let me point you to the documentation. I know it looks pretty bare bones, but it outlines both the hierarchy and functionality of all features in Arc.

1. Sprite Class

The sprite class is one of the more interesting pieces of code within Arc. It is a flexible graphical entity easily allowing you to represent either a single graphic, or a multi-animation multi-sound entity. First, let's take a look at how you would create a single frame Sprite.

[Get Code]
Sprite s = new Sprite("image.png", COLLISION_TYPE.BOX);

Simple, eh? All in one line. Now let's take a look at how to add multiple animations to our Sprite, with different times between frames, and have a sound effect play on one of the frames.

[Get Code]
Sprite s = new Sprite(COLLISION_TYPE.BOX);
s.addFrame("image.png", "animation", 100, null);
s.addFrame("image2.png", "animation", 1000, null);
s.addFrame("image3.png", "animation2", 1000, null);
s.addFrame("image4.png", "animation2", 100, new SoundFX("file.wav"));

The above code creates two animations. The first animation will display 'image.png' for 100 milliseconds and then display 'image2.png' for 1 second and loop. The second animation will display 'image3.png' for 1 second, then play 'image4.png' for 100 milliseconds as well as play the sound from 'file.wav'. If you enter a number less than 0 as the time, then once your animation reaches that frame it will get stuck on the animation with the -1 value for time.

Now, you may want to play back these animations, sprite has a 'setAnim("animation")' function. What this function does is set the current animation to the one you specify. If you want your animation to loop or not loop, then you can use the 'setAnimLoop("anim", true)' function. If you want to reset an animation back to the beginning, there is a 'resetAnim("anim")' function that will reset it back to the beginning.

To position the sprite, use function s.setPosition(x,y). To give the sprite a different color or change alpha values, use s.setColor(r,g,b,a). The color range for each variable is from 0 to 255. Also, Sprite has a collide() function that will collide a sprite with any other sprite, taking into account the type of collision detection that they each have. You can collide rectangles into circles, pixels into boxes, etc. You can also set arbitrary pivot points for the sprites with the s.setPivot(x,y) functions.

2. Freetype Fonts

Fonts are usually a pain to deal with, thankfully with Arc I've already dealt with them for you. You can load any FreeType2 font with arc, and display it at the size and color you want to. Here's an example.

[Get Code]
Font font = new Font("font.ttf", 32);

This will create a font from file 'font.ttf' and will make the fonts height be 32. To draw the font, use...

[Get Code]
font.draw("line1\nline2",x,y,r,g,b,a);

Notice font does support newlines. This will draw the text at position x,y with given color and alpha with 'font.ttf'

3. Input

Input handling should be made easy, and with Arc it is. First of all, to update the current input you have to call arc.io.input.process() every frame, this will poll the input and set the inputs values as necessary. Arc's input system has many features and can handle any type of input there is. First of all let me introduce you to the concept of 'hitting' a key vs. the concept of 'pressing a key down.' Sometimes you just want a key to register once right when you hit it (single fire type effect), and sometimes you want the key to register as long as your holding it down. To differentiate, Arc's input system allows you to use either 'arc.io.input.keyDown('r')' or 'arc.io.input.keyHit('r')'. Same goes for mouse. To tell if someone hit the LEFT mouse button, you would use 'arc.io.input.mouseHit(LEFT)', which would return true when someone hits the left mouse button. In order to get mouse X and Y variables, use 'arc.io.input.mouseX and .mouseY' To access the scroll wheel, use .wheelUp or .wheelDown. To access modifier keys, use .modifier(CAPS/SHIFT/ETC.). The documentation on input explains these things a little more clearly with example code.

4. Windowing

Arc allows you easy access to the window. Usually you just want to open and close the window, but sometimes you want to take a screenshot of the current window. To do this, use arc.io.window.screenshot("screen"). Arc will automatically create 'screen.bmp' screenshot file. To toggle fullscreen, use 'arc.io.window.toggleFullScreen()'. You can resize window by using 'arc.io.window.resize(width, height)'. Beware, resizing on Windows destroys all texture information, this is an SDL problem, and the SDL guys say this is a windows problem, so just keep this in mind. It works fine on Linux though.

5. Graphical primitives

Arc has 5 graphical primitives. Pixel, Line, Circle, Rectangle, and Image. I think the documentation does a good job showing how to use them. The fill variable is whether or not the primitive is filled in or not.

6. Particle Effects

Arc currently has some basic particle effects. You can control the number, colors, speed, gravity, and direction of your particles, as well as the image you want to represent your particle.

7. Miscellaneous

Arc contains a number of miscellaneous features, such as a doubly linked list that can go forward and backward, trig functions through 'triangle,' converting coordinates from polar to rectangular in 'point', loading prison style graphic maps, stand alone collision functions, and random utilities.

Summary

Well, by now you should have a good idea of what Arc is and what it can do. If you are interested in programming a full fledged game in Arc and need some examples on how this could be done, please read my next tutorial, which shows by example how to program a full fledged asteroids game in Arc.

Please visit me in my forums for comments and suggestions.


this tutorial is licensed under the Creative Commons license

/+ Multimedia development for the D Programming Language +/