A-Engine Nomenclature

A-Engine Nomenclature

Postby A-Man » January 4th, 2016, 6:55 pm

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: [Select all] [Expand/Collapse]
  1. set_hitbox[] #a frame component
  2.  
  3. {info} #info section opening tag
  4. {/info}
  5.  
GeSHi © Codebox Plus


#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: [Select all] [Expand/Collapse]
  1. center= 34, 99, 10 # a frame tag
  2. add_hp= 50
  3.  
GeSHi © Codebox Plus


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: [Select all] [Expand/Collapse]
  1. #works:
  2. [F=100] #frames; while a frame is actually a component, "F" is somehow considered a tag which you provide it with an id
  3. [/F]
  4.  
  5. #works
  6. [FRAME=100+3] #an alternative more verbose frame tag (suggested by Rhino.Freak)
  7. [/FRAME]
  8.  
  9. [F=$reg + 2] #doesn't work; will throw an error
  10. [/F]
  11.  
  12. {info}
  13. STANDING=0 #constant value
  14. WALKING=10
  15. {/info}
  16.  
GeSHi © Codebox Plus


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: [Select all] [Expand/Collapse]
  1. h<up>= 10 # go to frame 10 if the Up button for the controller of the object is being held
  2. c<K_ESCAPE>= 20 #go to frame 20 when escape key is clicked
  3. r<MOUSE_0>=30 # go to frame 30 if the left mouse button is released
  4.  
GeSHi © Codebox Plus


#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: [Select all] [Expand/Collapse]
  1. {info}
  2. |IGNOREGRAVITY|
  3. # other tags
  4. {/info}
  5.  
  6. [F=10]
  7. |STANDING|NOSHADOW|
  8.   img = 10 center = 10,10
  9. [/F]
  10.  
GeSHi © Codebox Plus


#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: [Select all] [Expand/Collapse]
  1. add_hp = @max_hp - @hp
  2. goto = IF (@h<0> == TRUE) THEN (50) ELSE (10); # goto frame 50 if the action button 0 is held, else goto 10
  3.  
GeSHi © Codebox Plus


#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: [Select all] [Expand/Collapse]
  1. x_vel=$a # local register
  2. y_vel=$G.my_register # named global register
  3. z_vel=$P.05 # permanent register
  4.  
GeSHi © Codebox Plus


#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: [Select all] [Expand/Collapse]
  1. #this is a line comment
  2. [F=10] # land from jump (can serve for description)
  3. /# This is a
  4. multiline
  5. comment
  6.  
  7. ends here#/
  8.   img=10 #other tags
  9. [/F]
  10.  
  11.  
  12.  
GeSHi © Codebox Plus


#8: Other Info on a .A File Structure:
In general, a .a file is composed of components of 3 types:
1-Main Components:
Code: [Select all] [Expand/Collapse]
  1. {main_component}
  2.   #tags here
  3. {/main_component}
  4.  
GeSHi © Codebox Plus

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: [Select all] [Expand/Collapse]
  1. [id_component=id]
  2.   tags here
  3. [/id]
  4.  
GeSHi © Codebox Plus

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: [Select all] [Expand/Collapse]
  1. sub_component[
  2.   #tags here
  3. ]
  4.  
GeSHi © Codebox Plus

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: [Select all] [Expand/Collapse]
  1. {info}
  2.   HP = 500 # starting health
  3.   MAX_HP = 500
  4.   #..etc
  5.   [img] #images
  6.     sheet[ dir="folder/spritesheet.png" w=100 h=100 rows=10 columns=10]
  7.     sheet[ dir="folder/spritesheet2.png" w=100 h=100 rows=10 columns=10]
  8.   [/img]
  9.   [mdl] #models
  10.     obj[ dir="folder/models/cube.obj" scale=100]
  11.   [/mdl]
  12.   [snd] #sounds
  13.   [/snd]
  14.   #..etc
  15. {/info}
  16.  
GeSHi © Codebox Plus

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: [Select all] [Expand/Collapse]
  1. {info}
  2.   HP = 500 # starting health
  3.   MAX_HP = 500
  4.   #..etc
  5.   {img} #images
  6.     sheet[ DIR="folder/spritesheet.png" W=100 H=100 ROWS=10 COLUMNS=10]
  7.     sheet[ DIR="folder/spritesheet2.png" W=100 H=100 ROWS=10 COLUMNS=10]
  8.   {/img}
  9.   {mdl} #models
  10.     obj[ DIR="folder/models/cube.obj" SCALE=100]
  11.   {/mdl}
  12.   {snd} #sounds
  13.   {/snd}
  14.   #..etc
  15. {/info}
  16.  
GeSHi © Codebox Plus


What do you guys think of the changes? And what would do you further suggest? I'd like to keep this thread as the ground for discussing syntax and style related stuff for the A-Engine.
Image
User avatar
A-Man
Infamous Pirate
 
Posts: 401
Joined: March 31st, 2015, 11:40 am

Re: A-Engine Nomenclature

Postby Rhino.Freak » January 6th, 2016, 11:11 am

So far I like the syntax.
They are easy to read and self explanatory.
Image
User avatar
Rhino.Freak
Site Admin
 
Posts: 534
Joined: March 31st, 2015, 12:09 pm
Location: Somewhea~

Re: A-Engine Nomenclature

Postby A-Man » January 24th, 2016, 11:37 am

Okay, so I've been working on some advanced feature of the A-Engine; scripts. Basically, you can now use scripts to do more advanced data manipulation:
Code: [Select all] [Expand/Collapse]
  1. <<-somescript
  2.   $a += 3;
  3.   IF ($a > 5) THEN
  4.     $a = $b / 5;
  5.   ELSE
  6.     $a *= $a;
  7.   END
  8.  
  9.   $l.i = 0; #the 'l' means that the register is local to this block only
  10.   ASLONGAS ($l.i < 5) REPEAT
  11.     $register += 5;
  12.     $l.i += 1;
  13.   END
  14.  
  15.   #you can manipulate variables directly
  16.   @x_pos += 100;
  17.   @max_hp = 10000;
  18.   @hp = 10000;
  19. somescript #end
  20.  
  21. [F=10]
  22. <<somescript>>  #call the above script when this frame starts
  23.  img = 10 center = 0,0 delay = 3 #etcetc
  24. [/F]
  25. [F=11]
  26.   <<script $a = 3; $b = 5; $c = 7; script  #can be used to directly set registers instead of normal set_reg= way of doing it
  27.   img = 11 center = 0, 0 delay =3
  28. [/F]
  29.  
GeSHi © Codebox Plus


Plans to use these for coding AI:
Code: [Select all] [Expand/Collapse]
  1. <<-INIT #INIT block runs once at first
  2.   $l.target = &get_nearest{@self.team != @team};
  3. INIT
  4.  
  5. <<-MAIN #MAIN block runs every game time step
  6.   IF ($l.target.z_pos > @z_pos) THEN
  7.     &hold_key{<u>}; #walk up
  8.   ELSE
  9.     &hold_key{<d>}; #walk down
  10.   END
  11.  
  12.   IF ($l.target.x_pos > @x_pos) THEN
  13.     &hold_key{<r>}; #walk right
  14.   ELSE
  15.     &hold_key{<l>}; #walk left
  16.   END
  17.  
  18.   IF (&distance_from_object{$l.target.screen_id} < 50) THEN
  19.     &tap_key{<0>, 1};
  20.   END
  21. MAIN
  22.  
GeSHi © Codebox Plus

Registers starting with 'l' as a prefix are local to the script only. Syntax of delimiters is inspired by Ruby-styled heredocs. I will go more in detail in the next update as this is not final. Any thoughts about the readability of this?
Image
User avatar
A-Man
Infamous Pirate
 
Posts: 401
Joined: March 31st, 2015, 11:40 am

Re: A-Engine Nomenclature

Postby Rhino.Freak » January 26th, 2016, 3:29 am

Would love to see some examples of how scripts can actually be implemented to do something we normally can't or is very tough to do.

Syntax is readable and pretty clear by the way
Image
User avatar
Rhino.Freak
Site Admin
 
Posts: 534
Joined: March 31st, 2015, 12:09 pm
Location: Somewhea~

Re: A-Engine Nomenclature

Postby A-Man » January 26th, 2016, 4:12 pm

1-The ability to set engine variables (e.g: @x_pos) to a value since set_reg doesn't allow that. For example, you can directly set your position to the center of the stage.

2-The ability to call miscellaneous functions like "&hold_key{}" and "&tap_key{}" which doesn't return a value, to make your character does things he doesn't.

The above 2 points are things you're not really supposed to do, but just in case someone needs more control to do something exotic that I haven't thought about.

3-It makes things easier if you use lots of expressions in your code; instead of having 10 set_regs, you can open up a script block and assign things neatly without being verbose by repeating 10s of set_regs. It also allows for as many temporary registers (local register ($l.name)) to use in a calculation as you wish, so it helps in dividing up big ugly expressions you may have.

4-Finally, you can re-use scripts everywhere by writing "<<name_of_block>>" inside the frame's body after defining them only once inside your file. Makes things more portable too, as you can group scripts that does a certain thing in one file, and then simply import and call the blocks in the .a files you need.

5-Most importantly, for scripting AI. Additionally, it opens doors to more possibilities for the future; (plugin system?)
Image
User avatar
A-Man
Infamous Pirate
 
Posts: 401
Joined: March 31st, 2015, 11:40 am

Re: A-Engine Nomenclature

Postby DaniTOOAwesome » July 20th, 2016, 8:02 pm

woah Aiman and team made its own language :p
DaniTOOAwesome
Registered User
 
Posts: 2
Joined: July 19th, 2016, 8:02 pm


Return to A-Engineer's Zone

Who is online

Users browsing this forum: No registered users and 2 guests