The A-Engine: A new Beat 'em Up game engine

[A-Man]

Spoiler (Click to View)

It has always been an increasing function of flexibility plotted against complexity when it came to developing tools; thus with every additional feature, you can only expect the complexity of that tool to increase (supposing you're willing to learn everything about it of course). The A-Engine is no different. As it supports additional features and extends with its tags, it's only natural for it to be viewed as a more complicated tool by developers. This complexity can cause a steeper learning curve, and that's when sensible naming conventions help a lot.

Simply put, I'd like to state and discuss the current naming conventions when developing for the A-Engine. Here goes the planned:

#1: Components:
All original components are fully lower case, with a '_' character to separate between words when needed:

Code:

set_hitbox[] #a frame component

{info} #info section opening tag
{/info}

#2: Tags:
With a few exceptions, all the original tags and component tags are lower case, with a '_' character to separate between words when needed:

Code:

center= 34, 99, 10 # a frame tag
add_hp= 50

The exceptions are limited to:
1- Tags which value can't change once set. These are tags which you can only set to a constant expression or value. For example: (the frame and the sequence tags are changed to upper case for the sake of staying consistent)

Code:

#works:
[F=100] #frames; while a frame is actually a component, "F" is somehow considered a tag which you provide it with an id
[/F]

#works
[FRAME=100+3] #an alternative more verbose frame tag (suggested by Rhino.Freak)
[/FRAME]

[F=$reg + 2] #doesn't work; will throw an error
[/F]

{info}
STANDING=0 #constant value
WALKING=10
{/info}

2-Input related tags. Because there are so many buttons on your keyboard, and so many options for input methods, tags related to that follow a special syntax: X<Z>
X being either "c" for clicks, "h" for holding, and "r" for releasing the key Z.
Z can be either 'up', 'down', 'left', 'right', '0', '1', '2', '3', '4', '5', '6', '7', '8' or '9' which correspond to keys set in the option menu for the controlling player, 'K_' + keyboard key name for a specific keyboard key, or 'MOUSE_' + 0, 1 or 2 for a specific corresponding mouse button. For example:

Code:

h<up>= 10 # go to frame 10 if the Up button for the controller of the object is being held
c<K_ESCAPE>= 20 #go to frame 20 when escape key is clicked
r<MOUSE_0>=30 # go to frame 30 if the left mouse button is released

#3: Switches:
All switches are fully uppercase, with no separator between words. A switch is to be placed in the beginning of the component's opening tag, and each switch should be surrounded by a pair of '|' characters :

Code:

{info}
|IGNOREGRAVITY|
# other tags
{/info}

[F=10]
|STANDING|NOSHADOW|
 img = 10 center = 10,10
[/F]

#4: Variables:
Variables begin with the character '@'. Like tags, variables are all lower case with words separated by a '_' character, except with input related variables, which are equivalent to the tags' but with a '@' at the beginning:

Code:

add_hp = @max_hp - @hp
goto = IF (@h<0> == TRUE) THEN (50) ELSE (10); # goto frame 50 if the action button 0 is held, else goto 10

#5: Registers:
Registers are prefixed with the character "$". Registers come of 3 types:
-Local registers: By default, registers through a to Z are available.  By default, registers through a to Z are available (upper and lower case), but you can add named registers with extra procedure.
-Global registers: Registers which value is shared between all objects and stages. Their names begin with 'G.' or 'g.'. By default, g.registers through 00 to 99 are available, but you can add named g.registers with extra procedure.
-Permanent/Preference registers: Registers which store values beyond a game's session (permanently saves values in a file). Their names begin with "P." or "p.". By default, p.registers through 00 to 99 are available, but you can add named p.registers with extra procedure.

Code:

x_vel=$a # local register
y_vel=$G.my_register # named global register
z_vel=$P.05 # permanent register

#6: Constants:
As of now, there are only 3 constants available: NONE, TRUE and FALSE. All upper case.

#7: Comments/Remarks:
Comments or Remarks in .a files is possible. For a single lined comment, just precede it with a '#' character. For multiline comments, they begin at a '/#' and end at '#/:

Code:

#this is a line comment
[F=10] # land from jump (can serve for description)
/# This is a
multiline
comment

ends here#/
 img=10 #other tags
[/F]

#8: Other Info on a .A File Structure:
In general, a .a file is composed of components of 3 types:
1-Main Components:

Code:

{main_component}
 #tags here
{/main_component}

These are usually used to enclose a main important portion of a .a file. A notable example of main components is the "{info}{/info}" component.

2-ID Components:

Code:

[id_component=id]
 tags here
[/id]

These are used for components which usually occur in lots and need to be recognized via ids. An example of an ID component is a frame "[F=id][/F]".

3-Sub Components:

Code:

sub_component[
 #tags here
]

Those are components which occur in lots, but don't usually need an id. An example for a sub component are all frame components; e.g "set_hitbox[ ]"



Changes and implications with the new naming rules:
1-Changing frame tags from lower case "[f= frame id][/f]" to upper case "[F= frame id][/F]" because frame ids can't change once set as noted in #2 exception 1.

2-Previously, we had:

Code:

{info}
 HP = 500 # starting health
 MAX_HP = 500
 #..etc
 [img] #images
   sheet[ dir="folder/spritesheet.png" w=100 h=100 rows=10 columns=10]
   sheet[ dir="folder/spritesheet2.png" w=100 h=100 rows=10 columns=10]
 [/img]
 [mdl] #models
   obj[ dir="folder/models/cube.obj" scale=100]
 [/mdl]
 [snd] #sounds
 [/snd]
 #..etc
{/info}

Now, because '' and the other tags don't need an id (only one of each is to be used when needed), they will become main components instead. Also, because "dir" and the other tags inside can't be changed once the assets are loaded, they need to be all upper case:

Code:

{info}
 HP = 500 # starting health
 MAX_HP = 500
 #..etc
 {img} #images
   sheet[ DIR="folder/spritesheet.png" W=100 H=100 ROWS=10 COLUMNS=10]
   sheet[ DIR="folder/spritesheet2.png" W=100 H=100 ROWS=10 COLUMNS=10]
 {/img}
 {mdl} #models
   obj[ DIR="folder/models/cube.obj" SCALE=100]
 {/mdl}
 {snd} #sounds
 {/snd}
 #..etc
{/info}

What do you guys think of the changes? And what would do you further suggest?