Counter-Strike 2D supports Lua scripts since Beta 0.1.1.4

It uses the Lua engine Version 5.1.4
Please visit the Lua homepage for a documentation and manual
www.Lua.org/manual/5.1/manual.html

Lua scripting in CS2D is based on events/hooks
Hooks work only SERVERSIDE and NOT CLIENTSIDE! (due to security reasons)

!!! ATTENTION !!!
Using many/complex Lua scripts can make the game slower. Wrong or excessive usage of certain
commands can lead to strange behavior, increased traffic, lags, connection loss or even crashs.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

AUTOMATICALLY EXECUTED FILES:

[sys\lua\server.lua]
CS2D will automatically load and execute "sys\lua\server.lua" when hosting a server.
(only if the setting "mp_luaserver" is "server.lua")

[maps\MAPNAME.lua]
In addition it will execute "maps\MAPNAME.lua" when loading a map as server (MAPNAME = name of map)
This happens AFTER executing "server.lua" and only if there is a Lua file for the current map!
(the setting "mp_luamap" has to be "1" as well)

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

HOW TO HOOK:

The following hooks are available. You have to create Lua functions and then you have to attach
these functions to the hook by using the command
addhook("hook", "function" [,priority])
CS2D will execute all attached functions whenever the corresponding hook action occurs in-game.

Priority is only important if there is more than one function attachted to the same hook!
Default is 0, higher numbers = higher priority, lower numbers (also negative) = lower priority.
The attached function with the HIGHEST priority is the LAST function which will be executed.
Moreover CS2D will take the return value of this function (if there is any)!
In most cases you will just omit the priority parameter (yes, it is [optional])!

CS2D will pass parameters to most functions. You can use these parameters but you don't have to!

Some of the hook-functions can also have a return value. This return value influences the way how
CS2D behaves. Returning nothing is like returning 0, "" or nil.
In many cases you can skip the actual action in CS2D by returning 1 (return 1).

Always use just the name of the hook/function for adhook! Don't enter the brackets or parameters!
Always write quotation marks around the hook- and the function-name when using addhook!
RIGHT: addhook("leave","myleavehook")				<- do it this way!
WRONG: addhook("leave(id,reason)","myleavehook(id,reason)")	<- this is NOT going to work!
WRONG: addhook(leave,myleavehook)				<- this is NOT going to work!

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

LIST OF AVAILABLE HOOKS:
---------------------------------------------------------------------------------------------------
HOOK NAME + PARAMETERS + RETURN VALUE			EVENT
---------------------------------------------------------------------------------------------------

[Time]
ms100()							every 100 milliseconds (1/10 sec)


second()						each second


minute()						each minute (60 sec)


always()						always (each frame, costs much CPU power)
							game runs at 50 fps = 50 times per second


[Basic]
startround(mode)					on start of round
-mode: start/end mode id


endround(mode)						on end of round
-mode: start/end mode id


mapchange(newmap)					on map change
-newmap: name of new map


parse(text)						on parse (console/binds/rcon)
-text: text/commands to parse
>return:	0 - proceed normally
		1 - normal parsing, ignore unknown cmds
		2 - skip CS2D parsing


trigger(trigger,source)					on trigger (once per trigger)
-trigger: trigger name
-source: triggered by 0=map/1=script
>return:	0 - proceed normally
		1 - don't trigger


triggerentity(x,y)					on trigger (for triggered entities)
-x: entity x position (tiles)
-y: entity y position (tiles)
>return:	0 - proceed normally
		1 - don't trigger


break(x,y)						on breaking a breakable entity
-x: breakable x (tiles)
-y: breakable y (tiles)


projectile(id,weapon,x,y)				on projectile/grenade impact
-id: id of player who shot
-weapon: weapon type of projectile
-x: x position of impact (pixels)
-y: y position of impact (pixels)


log(text)						on logging
-text: text line which will be logged
>return:	0 - proceed normally
		1 - don't log this line


rcon(cmds,id,ip,port)					on remote command execution
-cmds: received remote control command(s)
-id: player who sent the cmds (or 0 if player is not on server)
-ip: IP of cmd sender
-port: Port of cmd sender
>return:	0 - proceed normally (execute RCon commands)
		1 - don't execute RCon commands

		
clientdata(id,mode,data1,data2)			on clientdata request (see reqcld Lua command)
- id: player who sent this data
- mode: which kind of data
- data1: data value 1 (depends on mode. commonly X coordinate)
- data2: data value 2 (depends on mode. commonly Y coordinate)


[Player]
join(id)						on join
-id: player id


leave(id, reason)					on leave
-id: player id
-reason: reason id (0 normal, >0 kick/ban/timeout)


team(id, team, look)					on teamchange
-id: player id
-team: 0 spec, 1 t, 2 ct
-look: look id 0,1,2 or 3
>return:	0 - proceed normally
		1 - don't change team + close menu


spawn(id)						on spawn
-id: player id
>return:	"" - (nothing) spawn with regular items
		"x" - spawn with melee weapon only
		"typeid,typeid,..." - spawn with these items + melee


name(id, oldname, newname)				on name change
-id: player id
-oldname: old player name
-newname: new player name
>return:	0 - proceed normally
		1 - don't change name

serveraction(id,action)					on server action key
-id: player id
-action: action key 1,2 or 3

buy(id, weapon)						on buy
-id: player id
-weapon: type id of requested weapon
>return:	0 - proceed normally
		1 - don't allow buying


walkover(id,iid,type,ain,a,mode)			on walking over an item
-id: player id
-iid: item id
-type: item type
-ain: ammo in weapon / item count
-a: additional ammo
-mode: item mode
>return:	0 - proceed normally (collect?)
		1 - don't collect


collect(id,iid,type,ain,a,mode)				on collect
-id: player id
-iid: item id
-type: item type
-ain: ammo in weapon / item count
-a: additional ammo
-mode: item mode


drop(id,iid,type,ain,a,mode,x,y)			on drop
-id: player id
-iid: item id
-type: item type
-ain: ammo in weapon / item count
-a: additional ammo
-mode: item mode (silencer/laser color/...)
-x: drop x position (tiles)
-y: drop y position (tiles)
>return:	0 - proceed normally (drop?)
		1 - don't drop
		2 - drop and  never fade out the item


select(id,type,mode)					on select weapon
-id: player id
-type: item type
-mode: item mode


reload(id,mode)						on reload
-id: player id
-mode: reload action (1 start, 2 finish)


attack(id)						on attack
-id: player id


attack2(id,mode)					on attack2
-id: player id
-mode: weapon mode


move(id,x,y,walk)					on player movement
-id: id of player who moved
-x: new x position of player (pixels)
-y: new y position of player (pixels)
-walk: walked? (0 run, 1 walk)


movetile(id,x,y)					on moving on a different tile
-id: id of player who reached a new tile
-x: new tile x position (tiles)
-y: new tile y position (tiles)


hit(id,source,weapon,hpdmg,apdmg)			on hit/damage
-id: player id (the victim)
-source: source player id or 0 (the attacker)
-weapon: weapon type / source type id
-hpdmg: caused damage (health)
-apdmg: caused damage (armor)
>return:	0 - proceed normally
		1 - ignore this hit (no damage)


kill(killer,victim,weapon,x,y)				on kill
-killer: player id
-victim: player id
-weapon: weapon type id
-x: death x (pixels)
-y: death y (pixels)


die(victim,killer,weapon,x,y)				on death
-victim: player id
-killer: player id
-weapon: weapon type id
-x: death x (pixels)
-y: death y (pixels)
>return:	0 - proceed normally
		1 - drop bomb/flag only


use(id,event,data,x,y)					on use
-id: player id
-event: use event (1 h.follow,2 h.stop,3 defuse, 100 tr._use, 150 dyn obj.)
-data: additonal data
-x: use x (tiles) or hostage id
-y: use y (tiles)


usebutton(id,x,y)					on using a button
-id: player id
-x: button x (tiles)
-y: button y (tiles)


say(id,message)						on say
-id: player id
-message: actual chat message
>return:	0 - proceed normally
		1 - don't show message


sayteam(id,message)					on sayteam
-id: player id
-message: actual chat message
>return:	0 - proceed normally
		1 - don't show message


radio(id,message)					on radio
-id: player id
-message: radio message type id
>return:	0 - proceed normally
		1 - don't show message


spray(id)						on spray
-id: player id


vote(id,mode,param)					on vote
-id: player id
-mode: vote mode (1 kick, 2 map)
-param: player id or map


buildattempt(id,type,x,y)				on build attempt
-id: player id
-type: building type
-x: building x (tiles)
-y: building y (tiles)
-mode: building mode
>return:	0 - proceed normally
		1 - don't build


build(id,type,x,y,mode,objectid)			on (effective) build
-id: player id
-type: building type
-x: building x (tiles)
-y: building y (tiles)
-mode: building mode
-objectid: id of new building object
>return:	0 - proceed normally
		1 - don't build


flagtake(id,team,x,y)					on collecting flag (from base only)
-id: player id
-team: player team
-x: flag base x (tiles)
-y: flag base y (tiles)
>return:	0 - proceed normally
		1 - don't take flag


flagcapture(id,team,x,y)				on flag capturing (bringing flag to own base)
-id: player id
-team: player team
-x: flag base x (tiles)
-y: flag base y (tiles)
>return:	0 - proceed normally
		1 - don't capture flag


dominate(id,team,x,y)					on domination of a domination point
-id: player id
-team: player team
-x: domination point x (tiles)
-y: domination point y (tiles)
>return:	0 - proceed normally
		1 - don't dominate


bombplant(id,x,y)					on planting bomb
-id: player id
-x: bomb x (tiles)
-y: bomb y (tiles)
>return:	0 - proceed normally
		1 - don't plant


bombdefuse(id)						on defusing bomb
-id: player id
>return:	0 - proceed normally
		1 - don't defuse


bombexplode(id,x,y)					on bomb explosion
-id: player id (who planted the bomb)
-x: explosion x (tiles)
-y: explosion y (tiles)
>return:	0 - proceed normally
		1 - don't explode

hostagerescue(id,x,y)					on hostage rescue
-id: player id (who rescued the hostage)
-x: rescue tile x (tiles)
-y: rescue tile y (tiles)


vipescape(id,x,y)					on VIP escape
-id: player id (VIP)
-x: escape tile x (tiles)
-y: escape tile y (tiles)


menu(id, title, button)					on Lua menu button selection
-id: player who clicked a Lua menu button
-title: title of the Lua menu the player clicked
-button: id of button. 1-9 or 0 for cancel and X (closing)


[Object]
objectdamage(id,damage,player)				on dynamic object damage (or heal/repair)
-id: dynamic object id
-damage: damage value (negative value for heal/repair)
-player: player id (0 if not caused by player)
>return:	0 - proceed normally
		1 - don't damage/heal/repair object


objectkill(id,player)					on dynamic object kill
-id: dynamic object id
-player: killer player id (0 if not killed by player)

objectupgrade(id,player,progress,total)			on object upgrade (buildings)
-id: dynamic object id
-player: player who performs upgrade
-progress: upgrade progess (ranges from 1 to total)
-total: progress required for upgrade to finish
>return:	0 - proceed normally
		1 - don't upgrade object

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You can use all Lua commands in your CS2D Lua scripts.
Note that there are "CS2D Lua Commands" and ordinary "CS2D Commands". You need to use the "parse"
command to execute ordinary CS2D commands with Lua ( ordinary cmds: www.CS2D.com/help.php?cat=all )
You can also use the wrapper-functions from "wrapper.lua" instead of using "parse".

LIST OF CS2D LUA COMMANDS
---------------------------------------------------------------------------------------------------
FUNCTION + PARAMETERS		INFO
---------------------------------------------------------------------------------------------------

[Basic]
- print("text") 		show "text" in console

- msg("text")			send "text" as server message to all

- msg2(id,"text")		send "text" to a certain player (id) only

- parse("commands")		execute ordinary CS2D commands ( www.CS2D.com/help.php?cat=all )

- vars()			show Lua variables in main table

- funcs()			show Lua functions in main table

- addhook("hook","func",[prio])	attach a function to a hook (priority is an optional parameter)

- freehook("hook","func")	remove a function from a hook

- sethookstate("hook",enable)	Enable(1)/Disable(0) a hook completely

- menu(id,"title,b1,b2,...,b9")	Open a menu on the screen of a certain player (id=player id)
				or at the screen of every player (id=0)!
				title = title of the menu
				b1-b9 = button captions,
				use empty strings ("") for buttons you don't need! Attach @b at the
				end of title for a bigger menu or @i for an invisible menu
				Put ( and ) around a button caption to create a disabled button
				Put a | followed by a short text behind a button caption to add
				an additional description to a button
				Note that the title and all buttons are in one single string
				parameter with "," as separator!
				
- reqcld(id,mode)	Request data from a player client (id=player id) or from all clients (id=0)
					Mode specifies which date you will receive:
					Mode 0: Cursor position (cursor position on screen)
					Mode 1: Map scrolling
					Mode 2: Absolute cursor position (cursor position on map)
					The requested data wil be received later. You have to use the clientdata-hook
					to handle the incoming data!

[Timer]
- timer(time,"func",["p"],[c])	Create a timer which will call the Lua function "func" after a
				certain time in milliseconds (time).
				Moreover it can pass a string parameter (p) to this function.
				The timer calls the function once by default. However you can call
				it several times by entering a count value (c). Using 0 or lower
				count values will make the timer call the function infinite times.

- freetimer(["func"],["p"])	Remove timers which call a certain function with a certain param.
				Call this function without parameters or with empty strings as
				parameters to remove ALL timers.

[Image]
- image("path",x,y,mode,[pl])	Creates an image (dynamic object) on the map and returns the ID.
				Mode 0: floor image (covered by players etc)
				Mode 1: top image (covering players)
				Mode 2: HUD image (covering everything, part of the interface)
				Mode 3: super top image (covering everything on the map)
				Mode 101-132: draw under this player (id+100)
				Mode 201-232: draw over this player (id+200)
				Mode 133-164: draw over this player and over entities (id+132)
				When drawing at player, x and y are used this way:
				x<=0: do not rotate with player, x>0: rotate img with player
				y<=0: only draw if not covered by fog of war, y>0: draw always
				[pl] is an optional parameter. 0 (default value) means that
				all players see this image. If you set it to a player ID then
				only this player will see this image!
				The command returns the ID of the dynamic object image!

- imagecolor(id,red,green,blue)	Changes color of an image ( rgb values: www.colorpicker.com )

- imagealpha(id,alpha)		Changes opacity (0.0 transparent - 1.0 opqaue) of an image

- imageblend(id,mode)		Changes blendmode of an image: 0 for normal (default mode),
				1 for light, 2 for shade and 3 for solid

- imagescale(id,x,y)		Changes image scale factors (in other words: the image size)

- imagepos(id,x,y,rot)		Changes position and rotation (0-360) of an image

- freeimage(id)			Removes an image

- tween_move(id,time,x,y,[rot])		Creates a movement tween which moves the image to x,y in the given time (+rotates it if rot is specified)

- tween_rotate(id,time,rot)			Creates a rotation tween which rotates the image to the angle rot in the given time

- tween_rotateconstantly(id,speed)	Creates a constant rotation animation which rotates an image permanently (negative speed for counter clockwise rotation)

- tween_alpha(id,time,alpha)		Creates an alpha fade tween which changes the transparency of an image

- tween_color(id,time,r,g,b)		Creates a color fade tween which changes the color of an image

- tween_scale(id,time,x,y)			Creates a scale tween which changes the size of an image an image

!!! ATTENTION: ALL images will be removed on each roundstart !!!
!!! ATTENTION: Creating/changing many images causes much traffic/crashs/connection problems !!!

[Game]
- game("value")			Return a game state/setting:
				You can use ALL settings like sv_name to get their current
				value as string(!). Moreover you can get the following values:
				version, dedicated, phase, round, score_t, score_ct,
				winrow_t, winrow_ct, nextmap, port, bombplanted

[Map]
- map("value")			Return info about the current map:
				name, xsize, ysize, tileset, tilecount, back_img, back_scrollx,
				back_scrolly, back_scrolltile, back_r, back_g, back_b, storm_x,
				storm_y, mission_vips, mission_hostages, mission_bombspots,
				mission_ctfflags, mission_dompoints, nobuying, noweapons,
				teleporters, botnodes

[Tile]
- tile(x,y,"value")		Return a value of the tile at the tile position (X|Y):
				frame, property, walkable, deadly, wall, obstacle, entity

[Player]
- player(id,"value")		Return a value of a player:
				exists, name, ip, port, usgn, ping, idle, bot, team, look,
				x, y, rot, tilex, tiley, health, armor, money, score, deaths,
				teamkills, hostagekills, teambuildingkills, weapontype,
				nightvision, defusekit, bomb, flag, reloading, process,
				sprayname, spraycolor, votekick, votemap, favteam, speedmod,
				maxhealth, rcon
				Moreover there is:
				player(0,"table"): a Lua table with all player IDs
				player(0,"tableliving"): a Lua table with all living player IDs
				player(0,"team1"): a Lua table with all terrorist IDs
				player(0,"team2"): a Lua table with all counter-terrorist IDs
				player(0,"team1living"): a Lua table with all living terrorist IDs
				player(0,"team2living"): a Lua table with all living counter-terrorist IDs
				

- playerweapons(id)		Return a table containing the types of all items carried by
				this player
				
[Item]
- item(id,"value")		Return a value of an item instance:
				exists, name, type, player, ammo, ammoin, mode, x, y, dropped,
				droptimer
				Moreover there is:
				item(0,"table"): returns a Lua table with all dropped item IDs

- closeitems(id,range)		Returns a Lua table with all IDs of items which are close to
				the player specified with the id parameter. Only dropped items
				which are within the range will be returned. The unit for the
				range is tiles (range 1 equals 32 pixels for example)

- itemtype(type,"value")	Return a value of an item type:
				name, dmg, dmz_z1, dmg_z2, rate, reload, ammo, ammoin, price,
				range, dispersion, slot, recoil

[Entity]
- entity(x,y,"value")		Return a value of an entity at the tile position (X|Y):
				exists, typename, type, name, trigger, state, int0, int1,
				int2, int3, int4, int5, int6, int7, int8, int9, str0, str1,
				str2, str3, str4, str5, str6, str7, str8, str9, aistate
				(int0-9 and str0-9 are used for entity settings and are
				different for each entity type)

- randomentity(type,[ai],[i0])	Returns the tile x and y position (2 values!) of a random entity
				of a certain type or -100,-100 if no entity has been found.
				ai=only find entities with this AI state (-1 to ignore)
				i0=only find entities with this int0 value (-1 to ignore)

- inentityzone(x,y,type)	Checks if the tile position (x|y) is in the area of a certain
				entity type and returns true or false

- setentityaistate(x,y,ai)	Sets the AI state value of the entity at tile position (x|y)
				The AI state is set to 0 on each roundstart
				(commonly used for the Lua bot AI only!)

[Hostage]
- hostage(id,"value")		Return a value of a hostage:
				exists, health, follow, look, x, y, rot, tilex, tiley
				Moreover there is:
				hostage(0,"table"): a Lua table with all hostage IDs

- randomhostage([unused])	Returns the tile x and y position (2 values!) of a random
				living and unused (not following anyone) hostage.
				Returns -100,-100 if no hostage has been found.
				Set unused to 0 if you want to get used hostages as well!

- closehostage(playerid)	Returns the tile x and y position (2 values!) of the closest
				living and unused hostage to player.
				Returns -100,-100 if no hostage has been found.


[Object]
(dynamic objects are used for buildings, mines, Lua images, etc.!)

- object(id,"value")		Return a value of a dynamic object:
				exists, typename, type, health, mode, team, player, x, y, rot,
				tilex, tiley, countdown, rootrot, idle, rotvar, target, upgrade
				Moreover there is:
				object(0,"table"): a Lua table with all dynamic object IDs

[AI]
- ai_say(id,text)		Bot says something

- ai_sayteam(id,text)		Bot says something to the own team

- ai_radio(id,radioid)		Bot sends a radio message

- ai_goto(id,x,y,[walk])	Bot goes to tile (x|y). Set walk to 1 to let it walk (silent)
				Returns 0 when failed to find path, 1 when target is reached or
				2 when bot is still on its way.

- ai_move(id,angle,[walk])	Bot moves into certain direction. Set walk to 1 to let it walk.
				Returns 1 when successfull or 0 when way is blocked.

- ai_respawn(id)		Bot respawns (only if dead and only if game mode allows it)

- ai_findtarget(id)		Returns the ID of the closest enemey or 0 for no enemy

- ai_freeline(id,x,y)		Check if there is a free line between the bots and (x|y) (in pixels)

- ai_aim(id,x,y)		Bot aims at (x|y) (in pixels)

- ai_iattack(id)		Bot performs an intelligent attack (auto reloading & weapon switching)

- ai_attack(id,[secondary])	Bot performs a primitive attack. Set secondary to 1 to use the secondary
				weapon function (=attack2) instead of the primary function

- ai_buy(id,itemtype)		Bots tries to purchase a certain item (itemtype=integer id, not a string)

- ai_use(id)			Bot uses the environement (like pressing use-key)

- ai_rotate(id,angle)		Bot instantly turns to certain direction/angle

- ai_selectweapon(id,itemtype)	Bot selects a certain weapon (needs to have this weapon)

- ai_reload(id)			Bot reloads the current weapon

- ai_drop(id)			Bot drops the current weapon

- ai_spray(id)			Bot sprays a spraylogo

- ai_build(id,building,x,y)	Bot tries to build a building at tile position (x|y). Building has to be
				a building integer id, not a string. The position has to be a free tile
				next to the current position of the bot.

- ai_debug(id,text)		Set debug-text for bot (displayed if "debugai" is enabled)

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

www.Lua.org
www.UnrealSoftware.de
www.CS2D.com
www.USGN.de