The scripting system uses programming language Lua:
http://www.lua.org/
To add a new weapon, you need to place a script WeaponName.lua in the weapons folder. To take the weapon into use, you need to add it to the lists in Weapons.dat.
Alternatively, you can create a subdirectory for the weapon, which must have the same name as the weapon. (weapons/WeaponName/WeaponName.lua). This way you can put all additional files needed by the weapon in the same place. This is discussed in chapter 4.
This script could be used to define the "dumbfire" weapon:
max_energy = 60
req_energy = 60
recoil = 175
function launch()
dir = get_platform_dir()
dx, dy = get_dir_vector(dir)
create_object("dumbfire", dx*8, dy*8, dx*200, dy*200)
end
The launch method is called whenever the weapon is fired. It can use the Wings Lua API to create game objects, play sounds, etc.
The first lines define the weapon loading time (or energy use):
max_energy - maximum energy load of the weapon req_energy - energy required to launch the weapon recoil - how hard the weapon "kicks"
It is also possible to define:
req_energy_level - how much energy is required to start firing the weapon, even if req_energy is lower.
Example:
max_energy = 200 req_energy = 2 req_energy_level = 60 delay = 0.03
The delay gives (in seconds) the minimum time between two shots. If the delay is not given, the firing rate would depend only on framarate, which is not a good idea.
To create weapons which require several steps (trigger presses) to use, such as the harpoon, you can define the number of phases:
max_energy = 20 req_energy = 20 phases = 2
There is also an alternative load mode, which is currently used in the shotgun. It can be used to define weapons which can be shot multiple times before reloading.
Example:
load_mode = 2 req_energy = 110 num_shots = 6 shot_energy = 5
Here req_energy is the reloading energy, shot_energy is the energy required for each shot, and num_shots is the number of times the weapon can be launched before reloading.
To create weapons like the "gun", where you need to release and press the fire key again between two shots, you can define:
trigger_mode = 2
To create weapons like the grenade, where you can change the throwing strength by holding the key down, you can define:
trigger_mode = 3 max_power_time = 1
The time defines how long (in seconds) you need to hold the key for maximum power. The power (0-1) is given as an argument of the launch function:
function launch(power) ... end
The variables initialized at the start of the script are global - their values are same for all weapons of this type. For this reason, there is a special global table 'this', which may used to store the state of the the current weapon instance. (Say, the weapon in the ship of player 1.)
x = 0 function init() this.x = 0 end function launch() x = x + 1 this.x = this.x + 1 end
Here, 'x' is global, and using it will probably have unwanted effects when more than one player uses the weapon. 'this.x' will work correctly. The init() -function can be used to initialize the weapon state. (Using 'this' outside of a function will not work correctly.)
If you need to continuously check for something, for example state of an object you created (like a rope), you can add a new funtion:
function run() do_something() end
Game objects (such as bullets) can be created in the same way as weapons. Place script file object_name.lua in the main objects folder, or in a weapon object folder (weapons/WeaponName/objects).
Note that you can have only one object with a given name, no matter where the file is placed.
Graphics files needed by the objects can also be placed in the object folder. You also need to add file named "Graphics.xml", which defines the used images.
Similarly, sound files and "Sounds.xml" file can be added to weapon and object folders.
The following example script defines a simple projectile which causes some damage and vanishes when it hits the ship or some other object.
image = "bomb" condition = 12.0 bounding_circle_radius = 3 hit_damage = 10 hit_impulse = 1.5 mass = 2.0 volume = 0.5 air_resistance = 1.0 function init(x_pos, y_pos, x_vel, y_vel, owner_id) px, py = get_object_pos(owner_id) vx, vy = get_object_vel(owner_id) px, py = find_last_clear_point(px, py, px+x_pos, py+y_pos) set_pos(px, py) set_vel(vx+x_vel, vy+y_vel) set_owner(owner_id) end
The first part of the script defines some constants for the weapon. Changing the value of these variables later in the script has no effect.
The following list describes supported variables and default values.
gravity = true Selects whether this object is affected by gravity volume = 1.0 mass = 100.0 thrust = 0 Forward thrusting force. Object direction must have been defined with set_dir() for this to have an effect. This variable must be defined if set_thrust() function is used. lifetime = n If variable is defined, the object has limited lifetime of n seconds. static = true If this variable is defined, the object is attached to the ground. has_dir = false This must be defined true to use set_dir() -function. static_dir = false If this variable is defined as true, the object's direction will not be changed by any physical forces. image = "" If this variable is defined as non-empty string, the object will use a static image defined by the image name. hit_animation = "" If this variable is defined as non-empty string, the object will use this image when it is hit. image_x = 0 image_y = 0 Relative position of the image. animation = "" If this variable is defined as non-empty string, the object will use an animation defined by the animation name. hit_animation = "" If this variable is defined as non-empty string, the object will use this animation when it is hit. loop_animation = false If this variable is defined as true, the animation will loop. mirror_animation = false If this variable is defined as true, the animation will be mirrored when the object direction is to the left. pixel_size = 0 pixel_alpha = 0 pixel_r = 0 pixel_g = 0 pixel_b = 0 If this is defined as > 0, and no image or animation is defined, the object will be drawn as a point (or circle) of this size and color. condition = 0 If this variable is non-zero, the object will have condition, ie. it may take damage before it is destroyed. bounding_circle_radius = 1.0 Maximum distance used in collision detection. shoot_from_inside = true Selects whether the object to which this object is attached can shoot without hitting the attached object. (Example: the bubble) hit_damage = 0 The damage caused by this object. hit_impulse = 0 The impulse (kick) caused by this object. touch_damage = 0 If the object is not destroyed at first hit, this can be used to cause continuous damage. hit_ground = true If false, the object can pass through ground. ground_kills = true If true, the object will be destroyed when it hits ground. network_updates = false This must be be set true if the object uses network_update() function. send_reliably = false If true, created objects will be sent to clients using reliable protocol. check_hits = false If true, forces collision detection to be performed with these objects, even if max_condition is 0. can_hit_same_type = true If false, collisions between objects of this type will not be detected. remote_check_hits = false If true, collisions will also be detected on clients. remote_callbakcs = false If true, script callback function will be called also on clients.
In addition to the static definition, you can define several functions which are called when various events occur.
init([args]) Initialization function takes the arguments given by create_object() call. network_init() This function is called when the object is received from a remote machine, before reading its data. (Normal init function is not called, because arguments are not available.) on_call([args]) Called from this or an another object with function call_object(id, [args]) on_timer() Used with function set_timer(seconds) on_lifetime_end() If lifetime is defined, this function is called when it ends. on_hit_ground() Called when the object hits ground. on_hit_water() Called when the object hits water. on_hit_object() Called when the object hits another object. on_break() If condition is defined, this function is called when the object is broken. write_data() read_data() If the object has state variables in the script (this.something), then these functions are called to send and receive the state in network game. (See functions write_intX(), read_intX().)
These functions are only called in the server end, so all changes must be transferred over the network with an explicit call to the network_update() function.
Objects can use state variables (with 'this') in the same way as weapons, but their state must be transferred over the network. (See functions write_data(), read_data()).
id = create_object(name, ...)
object_list = get_objects_from(x, y, radius)
object_list = get_objects_from_line(x1, y1, x2, y2, radius)
call_object(id)
remote_call_object(id)
set_effect(id, effect_name, status)
state = is_alive(id)
s = is_solid(id)
type = get_object_type(id)
team = get_object_team(id)
team = get_object_owner(id)
team = get_object_player(id)
set_object_team(id, team)
c = get_object_condition(id)
c = get_object_max_condition(id)
m = get_object_mass(id)
m = get_object_size(id)
x, y = get_object_pos(id)
x, y = get_object_shoot_pos(id)
x, y = get_object_vel(id)
x, y = get_object_force(id)
dir = get_object_dir(id)
set_object_pos(id, x, y)
set_object_vel(id, vx, vy)
set_hold(held, holder)
cause_damage(id, damage)
kill_object(id)
enter_object(pilot_id, object_id)
EMP_hit(id, power)
add_object_force(id, x, y)
add_object_impulse(id, x, y)
set_rope_endpoint(rope_id, endpoint, object_id)
t = get_time()
t = is_server()
t = is_object_host(id)
dt = get_dt()
x, y = get_dir_vector(dir)
dir = get_vector_dir(x, y)
x, y = random_vector()
c = dir_change(dir1, dir2)
dir2 = change_dir(dir1, c)
d = distance(x1, y1, x2, y2)
find_first_solid_point(x1, y1, x2, y2)
find_last_clear_point(x1, y1, x2, y2)
find_last_nonsolid_point(x1, y1, x2, y2)
mx, my = get_map_pos(wx, wy)
mx, my = get_map_pos_rel(wx, wy)
wx, wy = get_world_pos(mx, my)
wx, wy = get_world_pos_rel(mx, my)
type = get_map_type(x, y)
(r,g,b,a) = get_map_color(x, y)
set_map_pixel(x, y, type, r, g, b, a)
local_set_map_pixel(x, y, type, r, g, b, a)
remove_map_pixel(x, y)
local_remove_map_pixel(x, y)
fire(x, y)
explode(x, y)
fg_activate(x, y, rad)
play_sound(name, [volume, [importance]])
add_team_points(team, points)
r = build_time_on()
send_game_message(text)
b = terrain.is_clear(type)
b = terrain.is_solid(type)
b = terrain.is_normal(type)
b = terrain.is_water(type)
b = terrain.is_mud(type)
b = terrain.is_sand(type)
b = terrain.is_snow(type)
b = terrain.is_strong(type)
b = terrain.is_indestructible(type)
b = terrain.is_base(type)
b = terrain.is_platform(type)
dir = get_platform_dir()
set_platform_dir(dir)
id = get_platform_id()
x, y = get_platform_pos()
x, y = get_platform_vel()
set_platform_pos(x, y)
set_platform_vel(x, y)
add_platform_impulse(x, y)
add_platform_force(x, y)
id = get_platform_load_speed()
power = get_current_power()
is_first_shot()
phase = get_phase()
set_phase(phase)
reset()
reset_phase()
set_wait_object(id)
set_pos(x, y)
set_vel(x, y)
set_dir(dir)
set_angular_vel(a)
set_thrust(t)
set_mass(m)
set_owner(id)
set_team(id)
set_text(name)
show_timer(time)
set_effect(name, status)
set_image(name)
set_animation(name)
set_anim_pos(time)
set_pixel_size(size)
set_pixel_color(r, g, b, a)
set_active(a)
id = get_owner()
id = get_team()
x, y = get_pos()
x, y = get_vel()
dir = get_dir()
id = get_id()
type = get_type()
c = get_condition()
a = get_age()
kill()
kill_local()
set_timer(t)
set_lifetime(t)
stop_timer()
f = timer_is_set()
attach_to(id)
id = get_attached_object()
attach_to_ground(b)
attached_to_ground()
set_attach_pos(dir, dist, dir2, fixed)
x, y = get_force()
add_force(x, y)
add_impulse(x, y)
set_force(x, y)
write_int8(value)
write_int16(value)
write_int32(value)
value = read_int8()
value = read_int16()
value = read_int32()
network_uodate(t)
id = create_object(name, ...)
Creates an object, returns id number of the created object. If the object could not be created, returns 0.
Arguments depend on the object being created. If it is a scripted object, see the init() function of the object.
Built-in objects:
bullet, dumbfire, explosion, explosion2, nucleus_explosion,
freezer, grenade, mine, shot, trooper:
create_object(name, x_pos, y_pos, x_vel, y_vel)
x_pos and y_pos and displacement in pixels from the
center of the platform. x_vel and y_vel are start
velocity. (Default bullet velocity is 220.)
Note: setting velocity does not work for mines.
harpoon
create_object("harpoon", type, x_pos, y_pos, x_vel, y_vel, dir)
Type 1 is large, type 2 is small.
particle
create_object("particle", x_pos, y_pos, x_vel, y_vel,
color_r, color_g, color_b,
size, water, lifetime, paint)
Particles are "visual only" objects, with no other effects.
Color is defined with RGB components, 0-255. Size is in pixels.
(Only size < 10 is supported, >= 10 is currently a special case.)
'water' tells whether the particle can move in water, true/false.
'lifetime' is time in seconds before the particle vanishes
'paint' tells whether and how much the particle changes color of
the ground it hits. It is a floating point number 0-1.
rope
create_object("rope", type, lifetime, obj1_id, obj2_id)
Type 1 is the "harpoon rope", type 2 is the "pilot rope".
Lifetime is time in seconds before the rope disappears.
Object ids define where the rope endpoints are attached.
Id 0 is valid input, but the rope will not be created.
Note: lifetime has no effect on type 2 rope.
laser beam
create_object("laser", obj1, obj2, team)
smoke
create_object("smoke", x_pos, y_pos, x_vel, y_vel,
color_r, color_g, color_b, lifetime)
ship
create_object("ship", x_pos, y_pos, x_vel, y_vel, dir)
splinter
create_object(name, x_pos, y_pos, x_vel, y_vel,
color_r, color_g, color_b)
Color is defined with RGB components, 0-255.
wave_particle
create_object("wave_particle_1", x_pos, y_pos, x_vel, y_vel, lifetime)
create_object("wave_particle_2", x_pos, y_pos, x_vel, y_vel, lifetime, [power])
Special invisible objects used in explosions. Type 1 destroys ground,
type 2 causes damage to objects. Default power is 1.
object_list = get_objects_from(x, y, radius)
Returns list of object id's which are located near the given position
object_list = get_objects_from_line(x1, y1, x2, y2, radius)
Returns list of object id's which are located near the given line.
call_object(id)
Calls the on_event() function of the given object, if it exists.
remote_call_object(id)
Calls the on_event() function of the given object on server, if it exists.
set_effect(id, effect_name, status)
Sets effect effect_name on object id on/off
state = is_alive(id)
Returns true if object 'id' is alive, false if not.
s = is_solid(id)
Returns true if object 'id' is solid, false if not.
type = get_object_type(id)
Returns type name of the object 'id'.
team = get_object_team(id)
Returns team number of the object 'id'.
team = get_object_owner(id)
Returns owner of the object 'id'.
team = get_object_player(id)
If the object 'id' is controlled by a player, return player id. Otherwise returns 0.
set_object_team(id, team)
Sets team number of the object 'id'.
c = get_object_condition(id)
Returns condition of the object 'id'.
c = get_object_max_condition(id)
Returns maximum condition of the object 'id'.
m = get_object_mass(id)
Returns mass of the object 'id'.
m = get_object_size(id)
Returns size (bounding circle radius) of the object 'id'.
x, y = get_object_pos(id)
Returns position of object 'id'.
x, y = get_object_shoot_pos(id)
Returns position where bullets shot by object 'id' should start from.
x, y = get_object_vel(id)
Returns velocity of object 'id'.
x, y = get_object_force(id)
Returns force affecting the object.
dir = get_object_dir(id)
Returns facing direction of object 'id'.
set_object_pos(id, x, y)
Sets position of object 'id'.
set_object_vel(id, vx, vy)
Sets velocity of object 'id'.
set_hold(held, holder)
Notifies object 'held' that it is being hold/attached by another object.
cause_damage(id, damage)
Damages object 'id'.
kill_object(id)
Removes object 'id'.
enter_object(pilot_id, object_id)
Enters ship/cannon/glider/etc, if possible.
EMP_hit(id, power)
Causes an EMP hit to object 'id'. Power is the length of the effect in seconds.
add_object_force(id, x, y)
Adds a force to object 'id'.
add_object_impulse(id, x, y)
Gives object 'id' an impulse.
set_rope_endpoint(rope_id, endpoint, object_id)
Attaches rope endpoint (0 or 1) to an object.
t = get_time()
Returns current game world time in seconds.
t = is_server()
Returns true if the script is running on server.
t = is_object_host(id)
Returns true if object 'id' is controlled by this computer.
dt = get_dt()
Returns length of the last frame in seconds.
x, y = get_dir_vector(dir)
Returns unit vector pointing at the given direction.
dir = get_vector_dir(x, y)
Returns direction of the vector in degrees.
x, y = random_vector()
Returns a random vector, length < 1.
c = dir_change(dir1, dir2)
dir1, dir2 = [0, 360), dir2 = c + dir1, c < 180.
dir2 = change_dir(dir1, c)
dir1, dir2 = [0, 360), dir2 = c + dir1, c < 180.
d = distance(x1, y1, x2, y2)
Returns distance between (x1, y1) and (x2, y2)
find_first_solid_point(x1, y1, x2, y2)
Returns the first solid terrain point in the line (x1, y1) - (x2, y2). Arguments are world coordinates.
find_last_clear_point(x1, y1, x2, y2)
Returns the last clear (air) terrain point in the line (x1, y1) - (x2, y2). Arguments are world coordinates.
find_last_nonsolid_point(x1, y1, x2, y2)
Returns the last non-solid terrain point in the line (x1, y1) - (x2, y2). Arguments are world coordinates.
mx, my = get_map_pos(wx, wy)
Converts world coordinates to map coordinates. World coordinates are used for object positions, map coordinates for terrain pixels.
mx, my = get_map_pos_rel(wx, wy)
Converts relative (to the calling object) world coordinates to map coordinates.
wx, wy = get_world_pos(mx, my)
Converts map coordinates to world coordinates. World coordinates are used for object positions, map coordinates for terrain pixels.
wx, wy = get_world_pos_rel(mx, my)
Converts map coordinates to relative (to the calling object) world coordinates.
type = get_map_type(x, y)
Returns terrain type in the map pixel (x, y).
(r,g,b,a) = get_map_color(x, y)
Returns color of the map pixel in (x, y).
set_map_pixel(x, y, type, r, g, b, a)
Sets terrain type and color of the map pixel (x, y).
local_set_map_pixel(x, y, type, r, g, b, a)
Sets terrain type and color of the map pixel (x, y). The change is not sent to other clients.
remove_map_pixel(x, y)
Clears map pixel (x, y).
local_remove_map_pixel(x, y)
Clears map pixel (x, y). The change is not sent to other clients.
fire(x, y)
Starts up fire if used on flammable material.
explode(x, y)
Starts up explosion if used on explosive.material.
fg_activate(x, y, rad)
Activates 'force grid'
play_sound(name, [volume, [importance]])
Plays a sound effect. The effect name must be defined in Sounds.xml in sounds folder. Volume is an integer between 0-128, importance is 1 or 2, 2 is considered more important. Default values are 128, 1.
add_team_points(team, points)
Adds points to the team.
r = build_time_on()
Returns true if base defence build time is on.
send_game_message(text)
Sends a game message. (Writes text in chat stream.)
b = terrain.is_clear(type)
b = terrain.is_solid(type)
b = terrain.is_normal(type)
b = terrain.is_water(type)
b = terrain.is_mud(type)
b = terrain.is_sand(type)
b = terrain.is_snow(type)
b = terrain.is_strong(type)
b = terrain.is_indestructible(type)
b = terrain.is_base(type)
b = terrain.is_platform(type)
b = terrain.is_solid(type)
b = terrain.is_normal(type)
b = terrain.is_water(type)
b = terrain.is_mud(type)
b = terrain.is_sand(type)
b = terrain.is_snow(type)
b = terrain.is_strong(type)
b = terrain.is_indestructible(type)
b = terrain.is_base(type)
b = terrain.is_platform(type)
dir = get_platform_dir()
Returns direction of weapons platform (ship or pilot). Directions are in degrees, 0 is up, 90 right.
set_platform_dir(dir)
Sets the direction of weapons platform (ship or pilot). Directions are in degrees, 0 is up, 90 right.
id = get_platform_id()
Returns object id of the weapons platform.
x, y = get_platform_pos()
Returns position of the weapons platform.
x, y = get_platform_vel()
Returns velocity of the weapons platform.
set_platform_pos(x, y)
Sets position of the weapons platform.
set_platform_vel(x, y)
Sets velocity of the weapons platform.
add_platform_impulse(x, y)
Gives a physical impulse to the weapons platform.
add_platform_force(x, y)
Adds a force to the weapons platform.
id = get_platform_load_speed()
Returns loading speed of the weapons platform.
power = get_current_power()
Returns current launch power (0-1) of the weapon.
is_first_shot()
Returns true if this is the first shot after user pulls the trigger.
phase = get_phase()
Returns the weapon's launch phase.
set_phase(phase)
Sets the weapons's launch phase.
reset()
Resets weapon state, loading starts from the beginning.
reset_phase()
Finishes the launch (using energy), and sets phase back to 1.
set_wait_object(id)
If id != 0, the weapon will not start reloading until object 'id' has been destroyed.
set_pos(x, y)
Sets position of the object.
set_vel(x, y)
Sets velocity of the object.
set_dir(dir)
Sets direction of the object in degrees.
set_angular_vel(a)
Sets rotation speed.
set_thrust(t)
Sets value of forward thrusting force. This has no effect if direction is not defined.
set_mass(m)
Sets mass of the object.
set_owner(id)
Sets id of the object.
set_team(id)
Sets team of the object.
set_text(name)
Changes text of this object.
show_timer(time)
Shows timer value above the object.
set_effect(name, status)
Sets an effect on/off.
set_image(name)
Changes image of this object.
set_animation(name)
Changes animation of this object.
set_anim_pos(time)
Jumps to the given time if there is an animation defined for the object.
set_pixel_size(size)
Sets size of pixel which is drawn if image or animation is not set.
set_pixel_color(r, g, b, a)
Sets color of pixel which is drawn if image or animation is not set.
set_active(a)
Sets activity status flag.
id = get_owner()
Returns owner of the object.
id = get_team()
Returns team of the object.
x, y = get_pos()
Returns position of the object.
x, y = get_vel()
Returns velocity of the object.
dir = get_dir()
Returns current direction of the object in degrees.
id = get_id()
Returns id number of the object. Cannot be used in init() method
type = get_type()
Returns object type of the object.
c = get_condition()
Returns current condition of the object.
a = get_age()
Returns age of the object in seconds.
kill()
Destroys the object.
kill_local()
Destroys local copy of the object in network game.
set_timer(t)
Starts a t second timer, which calls on_timer() function when it expires. Only one timer is supported, calling this function again overrides the old value.
set_lifetime(t)
Sets life time of the object
stop_timer()
Stops the timer.
f = timer_is_set()
Returns true if timer is running
attach_to(id)
Attaches the calling object to an another object. attach_to(0) removes the attachment.
id = get_attached_object()
Returns the object to which the calling object is attached, or 0.
attach_to_ground(b)
Attaches the object to ground if b = true, removes the attachment if b = false. Attached object will stay in place despite any physical forces.
attached_to_ground()
Return whether the object is attached to ground.
set_attach_pos(dir, dist, dir2, fixed)
If the object is attached to an another object, sets the relative position and orientation. The object is moved to dir by dist units, and then rotated by dir2 degrees. If fixed is true, the object is not moved when the attached object rotates.
x, y = get_force()
Returns force affecting the object for this frame.
add_force(x, y)
Adds a component to the force affecting the object for this frame.
add_impulse(x, y)
Gives a physical impulse to the object.
set_force(x, y)
Sets a constant force affecting the object
write_int8(value)
Writes a 8 bit integer to the output stream. (Value must be between 0-255, and it will be rounded down.) This function can only be used in write_data() callback.
write_int16(value)
Writes a 16 bit integer to the output stream. (Value must be between 0-65535, and it will be rounded down.) This function can only be used in write_data() callback.
write_int32(value)
Writes a 32 bit integer to the output stream. (Value must be between 0-(2^32-1), and it will be rounded down.) This function can only be used in write_data() callback.
value = read_int8()
Reads a 8 bit integer from the output stream. This function can only be used in read_data() callback.
value = read_int16()
Reads a 16 bit integer from the output stream. This function can only be used in read_data() callback.
value = read_int32()
Reads a 32 bit integer from the output stream. This function can only be used in read_data() callback.
network_uodate(t)
Updates the object's state in client machines. t = 1: quick, unreliable update t = 2: slow, reliable update