TheSos/allegrojs TheSos/allegrojs

  • Stars
    star
    161
  • Rank 233,470 (Top 5 %)
  • Language
    HTML
  • License
    Other
  • Created over 9 years ago
  • Updated over 3 years ago
Twitter logo Share LinkedIn logo Share Facebook logo Share
TheSos/allegrojs
github

TheSos

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

a HTML5 game making library

allegro.js

a HTML5 game making library

Website | GitHub | API reference | Examples | Download | Tutorial

What is allegro.js?

allegro.js is a simple structural programming library for creating browser based games using HTML5 canvas written in javascript. It aims to be a simple tool that is both easy to pick up for beginners and industry veterans alike as well as a go-to tool for game jams and cool things that run in a browser. That said, here are some cool selling points of allegro.js, to which it will hopefully live up to. It uses structural programming that was long lost among game developers, but still proves much more handy in situations that require swift and foolproof solutions and is much more understandable and readable for beginners with no prior knowledge of game programming.

  • Easy to pick up for beginners that never don't necessarily know video game programming or javascript at all
  • Works in all major browsers including mobile consistently and without fail using no dirty hacks
  • Great for rapid prototyping simple ideas and mechanics thanks to its structural nature
  • Best game jam solution out there thanks to browser-basedness and structural, non-OOP nature
  • Tutorial and docs getting anyone up to speed with it within one sitting

How do you use allegro.js?

Here's a simple Hello World code for allegro.js. Hopefully, it doesn't need much explanation.

function main()
{
	allegro_init();
	set_gfx_mode("canvas_id", 640, 480);
	clear_to_color(canvas,makecol(255,255,255));
	textout_centre(canvas,font,"Hello World!",SCREEN_W/2,SCREEN_H/2,24,makecol(0,0,0));
	return 0;
}
END_OF_MAIN();

And here is the html code you need to provide to launch this.

<!doctype html>
<html>
	<head>
		<script src="allegro.js"></script>
		<script src="exhello.js"></script>
	</head>
	<body>
		<canvas id="canvas_id" width="640" height="480"></canvas>
	</body>
</html>

Where allegro.js is the library file, and exhello.js contains the aforementioned code. This is all you need to get started! allegro.js aim is to provide a dive-in experience, without worrying about complicated concepts.

Who is allegro.js for?

I hope for allegro.js to be a tool perfectly suitable for absolute beginners, who never had experience using game engines, such as I was when I started in Allegro, but it is also perfectly suitable for experienced Javascript developers who are looking for a lightweight solution, game jammers seeking for a RAD game making tool, developers looking for a non-OOP tool to create games and obviously, hard core old school classic Allegro nerds who somehow prevailed and want to come back to using it.

Where can I learn allegro.js?

First up, read all of this README! Then, there are several placed you can go to get documentation

What can allegro.js do?

  • It load and draw images, using load_bitmap(), draw_sprite(), stretch_sprite(), rotate_sprite(), pivot_sprite(), rotate_scaled_sprite(), pivot_scaled_sprite(), blit(), stretch_blit()
  • It can load and play sounds, using load_sample() and play_sample()
  • it can draw primitives, using getpixel(), putpixel(), rect(), rectfill(), line(), vline(), hline(), triangle(), trianglefill(), polygon(), polygonfill()
  • It can load fonts and display text, using load_font(), textout(), textout_centre(), textout_right()
  • It can have timed interrupts, using intall_int(), intall_int_ex(), loop()
  • It can read mouse input using mouse_x, mouse_y, mouse_z, mouse_b
  • It can read keyboard input using key[KEY_*]
  • It can help you calculate stuff using RAD(), DEG(), distance(), dot(), distance2(), scale(), clamp(), scaleclamp(), lerp(), abs(), sgn(), angle(), andglediff()
  • It can log stuff to console using enable_debug(), log() and wipe_log()
  • It can wait for everything to load using ready() and display a progress bag using loading_bar()

Where did allegro.js come from?

allegro.js is a minimal javascript port of a really popular game programming library called Allegro 4 from the first decade of our century. Allegro 4 is a simple game programming library that abstracts a set of functions in C programming language to the developer allowing for simple and rapid creation of video games, without the need to program entity systems, classes and so on. Allegro 5 is the current Allegro version, but it differs greatly as to how the API works, thus alienating many hardcore Allegro users. This library aims to provide a simple wrapper for a subset of canvas operations making it look like good old Allegro.

What are the differences between this and original Allegro?

Since the underlying system is completely different for allegro.js (Allegro used C and a bit of assembly inside too), there are a bunch of things that doesn't make sense for allegro.js, but there are new things that make perfect sense here, while they didn't back in the days. As I will try to keep it as close to original as possible, not to break the feel, there are bound to be discrepancies, and I'll list them right here!

  • set_gfx_mode takes canvas id, and pixel dimensions as arguments.
  • rotate_sprite draws the rotated sprite centred, as opposed to top-left alignment
  • all of the colour modes are gone, as js has uniform standardised colour format
  • software 3d functions are gone, but you can still use WebGL!
  • helper math functions have been added
  • END_OF_FUNCTION() and LOCK_ macros are no longer necessary
  • game loop must be wrapped in a loop() function, as js doesn't support blocking code
  • assets are loaded asynchronously, thus ready() function wrapper lets you execute code ensuring everything has been loaded already.
  • ready() can display a custom loading bar as well as a default one
  • remove_all_ints() has been added for simplicity
  • a couple of keyboard keys might not work in js
  • all of keystrokes, except for F5 have preventDefault(), meaning that i.e. pressing backspace in game won't take you to previous website!
  • hardware accelerated functions, such as create_video_bitmap() are all gone, everything is accelerated in js anyways
  • sprite rotations take degrees as parameter instead of 0..256 fixed value
  • makecol always produces 32bit 0xAARRGGBB value and takes 4 components with optional alpha
  • makecolf has been added for 0..1 colors
  • arcfill, trainglefill and polygonfill added
  • masked_blit functions are no longer needed, sicne everythign relies on alpha channel
  • textprintf functions are gone, since textout can do the same without printf stuff
  • textout has a size argument now, due to all fonts being ttf
  • play_sample no longer supports panning

But can it really make games?

That's what it's made for! Here's exgame.js with comments stripped down. In under 50 lines of code, you can have an actual game!

var man,apple,bg;
var munch;
var apple_x=200,apple_y=200;
var player_x=100,player_y=100;
var score = 0;

function draw()
{
	draw_sprite(canvas,bg,0,0);
	draw_sprite(canvas,man,player_x,player_y);
	draw_sprite(canvas,apple,apple_x,apple_y);
	textout(canvas,font,"Score: " + score,10,20,24,makecol(255,255,255));
}

function update()
{
	if (key[KEY_UP]) player_y-=4;
	if (key[KEY_DOWN]) player_y+=4;
	if (key[KEY_LEFT]) player_x-=4;
	if (key[KEY_RIGHT]) player_x+=4;
	if (distance(player_x,player_y,apple_x,apple_y)<20)
	{
		play_sample(munch);
		apple_x = rand()%(SCREEN_W-32);
		apple_y = rand()%(SCREEN_H-32);
		score++;
		log("Apple eaten!");
	}
}

function main()
{
	enable_debug('debug');
	allegro_init_all("canvas_id", 640, 480);
	man = load_bmp("data/man.png");
	apple = load_bmp("data/apple.png");
	bg = load_bmp("data/grass.jpg");
	munch = load_sample("data/munch.mp3");
	
	ready(function(){
		loop(function(){
			update();
			draw();
		},BPS_TO_TIMER(60));
	});
	return 0;
}
END_OF_MAIN();

Who made allegro.js?

allegro.js was made by me, Sos Sosowski. I always liked Allegro 4, and it felt wrong that it's gone already, so I wanted to give it a new life in form of this library. I hope that not only Allegro freaks like me, but also people new to javascript, or even game making in general will pick this up and create amazing stuff.

If you have any questions, suggestions, bug reports or would like to show me a game made with allegro.js (I'd love to know!) Drop me a line!

And don't forget to join the #allegrojs IRC channel at Freenode!

Can I help create allegro.js?

Everyone is mostly welcome to help extend, fix and maintain allegro.js! But if you want to help creating allegro.js, please keep the following several things in mind. These will help me manage pull requests and allegro.js to stay clean of bloat and usable!

  • If you change anything, make sure to run full unit test on all major browsers before committing (Chrome, IE, Firefox, Opera, Safari, including mobile) If you don;t have access to some of these, leave a note, so that someone else can do it!
  • generate documentation using doxygen with provided Doxyfile, if you don't have access to it, leave a note and someone will do it!
  • Crunch allegro.js using Closure Compiler with following parameters: --compilation_level SIMPLE_OPTIMIZATIONS --generate_exports --js allegro.js --js_output_file alleg.js Similarly, if you don't have access to Closure or Java, leave a note!
  • allegro.js does not aims to be fully compatible with Allegro 4. There are heaps of things that made sense back then, under Windows 95 and DOS, but make no sense now.
  • Keep the code consistent! Here are some tips:
  • functions use function word_word(a,b,c,d); scheme
  • global variables use var wordword; scheme
  • we don't use CamelCase
  • internal globals use var _wordword; scheme
  • structs are defined as Objects ({}) and defined as follows for proper documenting: function BITMAP_OBJECT(w,h,canvas,context,ready,type) {}

What are the allegro.js licence terms?

allegro.js licence is the same old Allegro 4 gift-ware licence!

Allegro is gift-ware. It was created by a number of people 
working in cooperation, and is given to you freely as a gift. 
You may use, modify, redistribute, and generally hack it about 
in any way you like, and you do not have to give us anything 
in return.

However, if you like this product you are encouraged to thank us 
by making a return gift to the Allegro community. This could be 
by writing an add-on package, providing a useful bug report, 
making an improvement to the library, or perhaps just releasing 
the sources of your program so that other people can learn 
from them. If you redistribute parts of this code or make a game 
using it, it would be nice if you mentioned Allegro somewhere in 
the credits, but you are not required to do this. 
We trust you not to abuse our generosity.

By Sos Sosowski, 05 August 2015.
(originally written by Shawn Hargreaves, 18 October 1998)

DISCLAIMER: THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY 
OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO 
THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR 
PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE 
COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE 
FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT 
OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Changelog

v4.0.6

  • Fixed mouse_pressed and _released being flipped!
  • added load_base64_font()
  • changed default font from 'monospace' to a custom drawn cartoon font (looks good with outlines!)
  • fixed checks for null parameters into undefined type check
  • changed .5s to /2s to reduce fractions (that doesn't work, need to floor, or not?)
  • fixed *_sprite methods into centered rendering <- READ THIS ONE
  • fixed examples and tutorials accordingly

v4.0.5

  • finalised renaming
  • finished website

v4.0.4

  • changed name to allegro.js
  • changed file names accordingly, watch out!
  • pulled requests

v4.0.3

  • increased version number!

v4.0.2

  • fixed examples
  • fixed volume
  • rearranged code
  • fixed and styled documentation
  • added mouse mickeys
  • started on the website!
  • added mouse menu suppress option
  • added show_mouse and hide_mouse
  • wrote the tutorial
  • fixed up missing css files
  • cleaned up a bunch
  • added customizable key unsuppressing
  • added create_font
  • added structure reference
  • fixed docs

v4.0.1

  • This is the first version
  • lots of stuff still broken
  • todo: examples
  • todo: tutorial
  • todo: cleanup
  • todo: website
  • todo: set/get_volume
  • todo: fix/remove freq from play_sample
  • todo: crunched version
  • todo: reference style
  • todo: remove vga.ttf

More Repositories

1

funkpunk

Flashpunk modified to use GPU rendering! Port your FP games to mobile!
ActionScript
11
star
2

chkey

Keyboard emulator for CH340G cheap Arduino knockoff clones
C++
5
star