# Eliter Script Documentation

## About This Document:

This document is meant to teach you how to write scripts with Eliter Script. You can use your own favorite text editor to write your script and then just place it in the scripts sub-directory of eliter with a .job extension to try it out. Take a look at some of the other .job files in that directory to see example code. example.job is a great place to start. Good luck!

Oh and when you finish your job send it to me at sailorh@chibinet.com. If I like it, and you are willing, I will put it in the next release of eliter and it can use the internet ranking system.

Stuff to write still:

- Assigning functions to object members. (Basically you just do Job.gameloop => functionname; )
- Loading custom images and sounds. (See example scripts)
- More infor on built in Functions
- More Constants?
- Creating new gun routines.
- Fun with member variables.
- example.job
- ???
- Profit!

## Syntax:

The syntax in Eliter Script is a lot like C except for some significant differences:

- There are no "for" loops. You will have to construct "for" loops using "while" loop syntax. For example:

>     int i;
>     i = 0;
>     while(i<10){
>     i++;
>     // To something
>     }

- There is no "switch" statement.
- Variables do not need to be declared before they are used.
- Type conversions happen automatically so you don't have to worry about casting.
- If you do declare variables, they cannot be assigned a value on the same line they are declared on. This may be changed in the future, because, yes, I realize it is an inconvience. Example:

>     int i = 12; // This doesn't work
>     int j;
>     j = 12; // This works

- There is no "class" or "struct" or "typedef" keywords. However, you can make member variables my just simply referring to them. Since you don't need to declare variables you can do this as simply or if you prefer to have declarations, you can use them too:

>     x.y = 12; // This works
>     int z;
>     int z.y; // This also works

- There is a special => operator in Eliter Script. The idea of this operator is to simplify pointers. I have considered removing this operator and just using the assignment operator for the same purpose, but for now it is here so here is a brief description.

>     object e;
>     int x;
>     x = 1; // Sets x to "1"
>     e => x; // Makes e a reference to object x
>     e = 2; // Sets x to "2" (and also e to "2")
>     message(x); // Displays "2"

- No gotos. No labels. No pointers. No references. (except using the => operator)
- The & operator is not a bitwise AND, but rather a string concatonation operator.

>     x = "hi " & "there"; // this sets x to "hi there"

## Variable Types:

- int
- float
- double
- string
- object

## Eliter Objects:

The following is a list of objects from Eliter which are accessable by the scripting language and decriptions of their members.

### Job Object:

The Job object comes in as a global variable called "Job" and has several variables which specify information about the current job script. Here are it's members:

- name
- description
- music - Midi music file
- tilesimage - Background wrapped image
- difficulty
- reward - Not Implemented Yet.
- stars - Number of stars to show
- trails - ?
- gamespeed - Default 10. The speed which the gameplay occurs. lower is faster.
- tilesize - Size of tiles in tilesimage
- tilexspeed - Speed that tiles (and stars) move
- tileyspeed - Speed that tiles (and stars) move
- screenxspeed - Speed that screen moves (moves entities with it)
- screenyspeed - Speed that screen moves (moves entities with it)
- style - CLASSIC or VERTICAL or HORIZONTAL
- nointernetranking - set to 1 to disable the prompt for internet ranking dialog
- highscore - The highscore for this level
- start - Reference to a function to be executed when the level begins.
- gameloop - Reference to a function to be executed every gameloop (every gamespeed miliseconds).
- finish - Reference to a function to be executed when the level ends. (May not be implemented?)
- onshoot - Reference to a function to be executed when the player shoots his gun. (Overrides the default gun code.)
- onspecial - Reference to a function to be executed when the plaeyer shoots his secondary fire. (Overrides the default speical gun code.)
- oninput - Not Implemented Yet.

### Player Object:

The player object encapuslates properties about the player's ship and status in an object that you can access and modify in the scripting language. The player object is accessed through a global variable called "Player". Actually, these are mostly useful for reading information, if you change most of these values it will either make the game act odd, or not do anything. But you can feel free to mess with whatever you want. Here is a list of members:

- sx - The location of the top-left corner of the player on the screen.
- sy - The location of the top-left corner of the player on the screen.-
- sxl - The width of the player .
- syl - The height of the player .
- ix - The location of the top-left corner of the player on the image file.
- iy - The location of the top-left corner of the player on the image file.
- ixl - The width of the player on the image file.
- iyl - The height of the player on the image file.
- draw - Whether or not the player is visible. 1 means visible, 0 means not.
- rotate - The number of degrees which the player sprite is rotated - use angle instead.
- lastx - The last sx position of the player. (used by the game to calculate movement and collision.
- lasty - The last sx position of the player. (used by the game to calculate movement and collision.
- warp - The speed multiplier used when you complete a level that makes the stars stretch.
- shooting - 1 if the player is holding the button to fire the primary gun. 0 otherwise.
- gun - Specifies what gun powerups the player currently has.
- specialammo - Specifies how many "Specials" (missiles, etc) the player has.
- special - Specifies the currently selected special weapon.
- score - The players current score.
- highscore - 1 if the player has made a new highscore, 0 otherwise.
- mx - x momentum
- my - y momentum
- mz - not used?
- angle - The direction the player is facing.
- state - Player state. I don't recommend setting this value, cause it may cause strange things... but these are the values:
  - 1 - Normal
  - 3 - Invulnerable
  - 4 - Dead
  - 5 - Sheild (not used?)
  - 6 - Light (not used?)
  - 7 - Flyin (don't use)
  - 8 - Flyout (don't use)
- anim - Frame of animation (0 or 1).
- count - Not used?
- success - Success value. Set this value before you end a mission with gameover() to decide the mission status screen to display. Should be:
  - NONE - No completion yet. Returns to the title screen.
  - FAILED - Failed the mission. Shows mission failed screen.
  - OK - Passed the mission. Shows mission complete screen.
  - PERFECT - Passed the mission "perfectly". This should be difficult to accomplish, not the same as OK. Shows mission perfect screen.
- health - how much health the player has (default 1)
- maxhealth - Maximum health/starting health (default 1)
- slow - Slowmode time remaining. 0 if slowmode is not active. > 0 activates slowmode.
- cheating - Whether or not the player has entered a cheat code or something that makes the highscore invalid. 1 means cheating, 0 means everything is cool.

### Entity Object:

The entity object is the basics of what makes up the game. It is every enemy you see on the screen. There are some built in entity base types that you can use or you can modify them to fit your needs. These are the defaults:

- LITER - The 2 liter bottles that fly up from the bottom of the screen.
- SODA - The pop cans that spin and fly in a straight line.
- NACHO - The nacho cheesies that home and chase after you.
- TRISCUT - The crackers that just sort of slowly float down by blow up big.
- JONES - The giant Jones soda bottle.
- ITEM - An item. Set the anim value to decide what gun powerup. See Constants section for details.
- SHOT - A simple enemy shot. Small little round bullet that hurts you.
- WALL - A undamageable wall.
- NONE - A base entity for you to build on.

To create an entity use the following code:

>     object e;

>     e => NewEntity(LITER, "My First Entity", MAIN_LAYER_TOP)

>     				// first parameter should be one of the constants from above.

>     // second parameter is an optional name string.

>     //
>     				third parameter is draw order explained below

Note the use of the => operator. The NewEntity function returns a reference to an Eliter Entity object, so you must use the => operator to make "e" point to that new entity. From here on you can reference "e"'s members like this:

>     e.sx = 100;

>     				e.xy = 200;

The third parameter is optional, but useful if you are having problems with entities overlapping each other. In those cases the third parameter allows you to specify a drawing order, it can be one of the following:

- MAIN_LAYER_TOP - This means the object will be drawn on top of previously created entities. This is the default value if you omit this parameter.
- MAIN_LAYER_BOTTOM - This means the object will be drawn below previously created entities.
- TOP_LAYER_TOP - This means the object will be drawn on top of all previously created entities in the top layer. The top layer is used for objects which should always be drawn on top, such as the HUD.
- TOP_LAYER_BOTTOM - This means the object will be drawn below all previously created entities in the top layer, but still on top of all entities in the main layer. The top layer is used for objects which should always be drawn on top, such as the HUD.
- BOTTOM_LAYER_TOP - Does not currently work.
- BOTTOM_LAYER_BOTTOM - Does not currently work.

Simple huh? What's "sx" and "sy" you ask? Well here is a list of all the entity members:

- sx - The location of the top-left corner of the entity on the screen.
- sy - The location of the top-left corner of the entity on the screen.-
- sxl - The width of the entity.
- syl - The height of the entity.
- ix - The location of the top-left corner of the entity on the image file.
- iy - The location of the top-left corner of the entity on the image file.
- ixl - The width of the entity on the image file.
- iyl - The height of the entity on the image file.
- draw - Whether or not the entity is visible. 1 means visible, 0 means not.
- rotate - The number of degrees which the entity is rotated.
- mx - The x momentum which the entity moves across the screen each gameloop.
- my - The y momentum which the entity moves across the screen each gameloop.
- mz - Reserved for specific entity types. For Triscut type entities, this value is the speed of the triscut rotation. Set it to 0 and rotate to 0 to prevent the triscut from rotating.
- screenattach - Specifies if the entity should move with the screen x and y speed (specified in the Job object). 1 means it should, 0 means it should only move based on its own mx and my.
- score - The amount of score the player receives for killing this entity.
- debris - The number of debris particles to make when it dies.
- anim - The current animation frame. If this value and maxanim are used, then the current ix will be offst by ixl*anim and anim will increment every frame until it gets to maxanim, at which time it will reset to 0.
- maxanim - The max animation frame before anim resets to 0.
- itemspawnchange - The percent likeliness that an item will be left behind when this enemy dies. The value should be between 0 and 100. 100 being 100% of the time this enemy will drop an item. Default is 13.
- collidemode - Specifies which other entities this object will collide with. Should be one of the following:
  - COLLIDE_NOTHING - Never collides with anything, not even player shots. (Fast!)
  - COLLIDE_SHOT - Collides only with player shots.
  - COLLIDE_DIFFERENT - Collides with objects of a different TYPE.
  - COLLIDE_DIFFSHOT - Collides with objects of a different TYPE and player shots.
  - COLLIDE_ENTITY - Collides with all entities.
  - COLLIDE_ALL - Collides with all entities and with player shots.
- friendly - Specifies whether this entity collides with the player. 0 means it does collide, 1 means it does not.
- explosion - Specifies that this entity blows up like a Triscut when it dies. 1 if it does, 0 if it doesn't.
- health - Current health. When this value reaches 0 or is set to 0, the entity "dies" and it triggers an onkill event if one is assigned. (See below)
- maxhealth - Starting health.
- damage - The amount of damage dealt to the entity in the last call to ondamage.
- collidetarget - The object which collided with this one in the last call to oncollide or onplayercollide. This is useful inside the collide functions, but you should note that after a collision takes place it is likely that this target object may die causing this value to be useless.
- onkill - Reference to a function which is executed when the entity dies.
- onalive - Reference to a function which is executed every gameloop for this entity. Be careful using this because if many entities have a onalive routine or the routine is processor intensive you may experience a drop in framerate.
- onplayercollide - Reference to a function which is executed when the entity collides with the player.
- oncollide - Reference to a function which is executed when the entity collides with another entity or a shot. (Make sure the collidemode is set correctly otherwise this will not be called.) This function is always called before ondamage.
- ondamage - Reference to a function which is executed when the entity takes damage. The function you assign to this must return an integer value. That value is how much damage to deal. If you return 0, the entity will never be hurt. You can see how much damage is supposed to be dealt by looking at this damage member of this this object.
- image - An index number of a image file to use. Only set this variable to a value returned from load_image or to 0. Setting it to any other value will likely result in crashing the game!

### Shot Object:

Create a new shot with the NewShot function as so:

>     object s;
>     s = NewShot(SHOT, SHOTSPEED, Player.rotate, 0, -1, 0, 0);

Simple eh? The first parameter is the type of shot which should be one of the following:

- SHOTNORMAL
- SHOTBEAM
- SHOTSHIELD
- SHOTMISSILE
- SHOTHOMING
- SHOTEXPLOSION

The second parameter is the speed the shot travels. Default is SHOTSPEED. or SHOTSPEED*2 for SHOTBEAM type.

The third parameter is the angle that the shot is facing, this is used to rotate the sprite and to calculate momentum. This doesn't work very well with SHOTBEAM right now, because the collision box is not rotated, causing odd collisions if the beam is rotated horizontally... I am working on a solution for this.

The fourth and firth parameters are the x and y offset from the center of the player of where the shot should be created. (0, -1) is the middle front of the player, (0, 1) is the middle back, (-1,0) is the middle left ect. You can use decimals and values greater than 1 also. So for example (-0.5, -2) will make a shot a 1/2 the players width to the left and 1 whole of the players height above the center of the player sprite. It may sound confusing but it works well.

The last two parameters are wavespeed and wavesize respectively. Try playing with them to create interesting movement patterns. Otherwise set them to 0 to not wave.

Once you got a shot object, use these members to play with it:

- sx - The location of the top-left corner of the shot on the screen.
- sy - The location of the top-left corner of the shot on the screen.
- sxl - The width of the shot.
- syl - The height of the shot.
- ix - The location of the top-left corner of the shot on the image file.
- iy - The location of the top-left corner of the shot on the image file.
- ixl - The width of the shot on the image file.
- iyl - The height of the shot on the image file.
- draw - Whether or not the shot is visible. 1 means visible, 0 means not.
- rotate - The number of degrees which the shot is rotated. Also used to calculate momentum for wave shots.
- mx - The x momentum which the entity moves across the screen each gameloop.
- my - The y momentum which the entity moves across the screen each gameloop.
- mz - Reserved for specific shot types.
- score - The amount of score the player receives for killing this entity.
- debris - The number of debris particles to make when it dies.
- anim - The current animation frame. If this value and maxanim are used, then the current ix will be offst by ixl*anim and anim will increment every frame until it gets to maxanim, at which time it will reset to 0.
- maxanim - The max animation frame before anim resets to 0.
- itemspawnchange - The percent likeliness that an item will be left behind when this enemy dies. The value should be between 0 and 100. 100 being 100% of the time this enemy will drop an item. Default is 13.
- collidemode - Specifies which other entities this object will collide with. Should be one of the following:
  - COLLIDE_NOTHING - Never collides with anything, not even player shots. (Fast!)
  - COLLIDE_DIFFERENT - Collides with objects of a different TYPE and player shots.
  - COLLIDE_ENEMY - Collides with all enemies and with player shots.
  - COLLIDE_SHOTONLY - Collides only with player shots.
- friendly - Specifies whether this entity collides with the player. 0 means it does collide, 1 means it does not.
- explosion - Specifies that this entity blows up like a Triscut when it dies. 1 if it does, 0 if it doesn't.
- health - Current health. When this value reaches 0 or is set to 0, the entity "dies" and it triggers an onkill event if one is assigned. (See below)
- maxhealth - Starting health.
- damage - The amount of damage dealt to the entity in the last call to ondamage.
- collidetarget - The object which collided with this one in the last call to oncollide or onplayercollide. This is useful inside the collide functions, but you should note that after a collision takes place it is likely that this target object may die causing this value to be useless.onkill - Reference to a function which is executed when the entity dies.
- onalive - Reference to a function which is executed every gameloop for this entity. Be careful using this because if many entities have a onalive routine or the routine is processor intensive you may experience a drop in framerate.
- onplayercollide - Reference to a function which is executed when the entity collides with the player.
- oncollide - Reference to a function which is executed when the shot collides with an entity. This function is always called before ondamage.
- ondamage - Reference to a function which is executed when the entity takes damage. The function you assign to this must return an integer value. That value is how much damage to deal. If you return 0, the entity will never be hurt. You can see how much damage is supposed to be dealt by looking at this damage member of this this object.
- image - An index number of a image file to use. Only set this variable to a value returned from load_image or to 0. Setting it to any other value will likely result in crashing the game!

## Function Reference:

Eliter has several built in functions to assist you in making awesome scripts.

- NewEntity(type, name)
- NewTimer(time, count)
- NewShot(type, speed, angle, offsetx, offsety, wavespeed, wavesize)
- GetEntity(name)
- GetPlayer()
- LoadSound(filename)
- PlaySound(soundindex)
- LoadImage(filename)
- UnloadImage(imageindex)
- random(i) - Returns a random number between 0 and i.
- randomx() - Returns a random number between -screenwidth and screenwidth*2
- randomy() - Returns a random number between -screenheight and screenheight*2
- sin
- cos
- tan
- asin
- acos
- atan
- exp
- log
- log10
- pow
- sqrt
- message(text, time) - Displays text at the top of the screen for time gameloops. (100 = 1 sec)
- gameover() - Ends the current game using the status condition specified in Player.status.

Globals/Contants

- true = 1
- false = 0
- eliter_version - The current version number
- screenwidth - width of the screen (area of the radar is 3 times this)
- screenheight - height of the screen (area of the radar is 3 times this)
- currentfps - The current FPS
- PI = 3.141592654
- Gun Types (set anim value for item object to specify one of these powerups)
  - GUNSPEED = 1
  - GUNWAVE = 2
  - GUNBEAM = 3
  - GUNSPREAD = 4
  - GUNDUAL = 5
  - GUNTRI = 6
- Time keywords
- SEC or SECOND = 100 - useful for Timer objects 3*SEC is the same as 3 seconds
- MIN or MINUTE = 6000 - useful for Timer objects 3*MIN is the same as 3 seconds

Notes:

images must be texture size multiples. 64, 128, 256, 512, 1024, etc... otherwise you will experience stretching and weirdness.