ESPy Tutorials

[Svendy]

All right, so i have been asked a few times to learn people to script, and well here it goes.
i will go through the coding in my tutorials line by line, although skipping stuff which have been covered in previous tutorials.
if you have any questions, problems, suggestions, requests or find any errors in the codes, feel free to post.
Attention: all parts with event_var[''] can be found in the categories @ http://www.eventscripts.com/pages/Category:Valve_Events
Everything in the tutorials after a # is comments and can be left out in the final codes.
when saving you code save it as addon_name.py and in the folder:
cstrike - addons - eventscripts - addon_name - addon_name.py
to test them out type es_load <addon_name> in your console.

1st. get these things:
EventScripts v2.0.0.250i Public Beta2 from http://mattie.net/cs/
Es_Tools Version 0.420 from http://forums.eventscripts.com/viewtopic.php?t=3413
the next 2 are optional, but will come in handy.
Notepad++ Version : 5.4.3 from http://notepad-plus.sourceforge.net/uk/download.php
Notepad++ EventScripts Python Highlighter 1.0.1 30/12/08 from http://forums.eventscripts.com/viewtopic.php?t=28262

2nd. you will most likely have to use the eventscripts wiki @ http://python.eventscripts.com/pages/Main_Page

==========================

Tutorial 01
Telling a player he has jumped

# The first thing you need to do is, in the first line type 'import es' you dont need to understand why ATM but its a must!
import es

# 'def player_jump(event_var):' is a function fired every time a player jumps.
def player_jump(event_var):
	# 'es.tell' will tell the player he has jumped.
	# the syntax of es.tell is: es.tell(<identifier>,<'message'>)
	es.tell(event_var['userid'], "You have jumped!")

Tutorial 02
Creating Freekill-Tell

# This is my first script, its currently running on the SG PB server

import es

# 'def player_hurt(event_var):' is a function fired every time a player gets hurt.
def player_hurt(event_var):
	# Check if the attacker is a CT
	# the 'if' statement is used for this.
	# the 'if' syntax is: if <var1> <operator> <var2>:
	# in this case the operator is the '==' which mean var1 is the same as var2
	if event_var['es_attackerteam'] == 3:
		# Check if it was friendly fire
		# here the operator '!=' is used, it means var1 is not equal to var2
		if event_var['es_userteam'] != event_var['es_attackerteam']:
			# tell the victim who he was attacked by and with what weapon:
			# the '%s' is where a variable would be, its inserted to the string after the '%' and within the parentheses of '%()' each variable separated by a comma
			es.tell(event_var['userid'], "You have been attacked by %s with the weapon %s" % (event_var['es_attackername'], event_var['es_attackerweapon']))

Tutorial 03
Add 1 kill using a chat command

import es

# 'def player_say(event_var):' is a function fired every time a player types something in chat.
def player_say(event_var):
	# check if the text typed in chat is !addkill
	if event_var['text'] == '!addkill':
		# add 1 kill to the players score
		# es.server.cmd is used for running est_ commands like 'est_KillAdd'
		# es.server.cmd syntax is: es.server.cmd("command")
		# est_KillAdd syntax is: est_KillAdd <identifyer> <value>
		es.server.cmd("est_KillAdd %s 1" %event_var['userid'])

Tutorial 04
A simple heal script

# for this we need to import the module 'playerlib' it give access to a huge list of functions for player manipulation
# for multiple imports, separate each module with a comma
import es, playerlib

def player_say(event_var):
	# store the player who typed in the variable 'player'
	player = playerlib.getPlayer(event_var['userid'])
	# store the players health in the variable 'hp'
	# since we stored a player through playerlib, we can use methods from the playerlib module, in this case the '.get()' method
	hp = player.get('health')
	# check if the player typed '!heal'
	if event_var['text'] == '!heal':
		# check if the player has 30 hp or less
		# here the '<=' operator is used, it means less than or equal to 
		if hp <= 30:
			# add 30 hp to the players health by using the playerlib method '.set()'
			# this methots syntax is: .set('health', var)
			# in python you can do simple math very simply as shown below
			player.set('health', hp + 30)
			# tell the player he has gained 30 hp
			es.tell(event_var['userid'], "You have gained 30 hp")
		# if the player has more than 30 ph
		# the 'else' syntax is plausible the easiest: else:
		else:
			# tell the player he has enough hp
			es.tell(event_var['userid'], "You got enough hp")

Tutorial 05
Make a welcome popup

# here we need to use the popuplib
import es, popuplib

# 'def load():' is fired every time the script is loaded onto the server
def load():
	# create the popup using the popuplib method '.create('name')'
	popup = popuplib.create('welcome')
	# add a line of text to the popup by using the '.addline('') method
    popup.addline('Welcome to the server!')

# 'def unload():' is fired every time the script is unloaded from the server
def unload():
	# delete the popup using the method '.delete('name')'
	popuplib.delete('welcome')

# 'def player_connect(event_var):' is fired every time a player connects to the server
def player_connect(event_var):
	# send the popup to the player using the '.send('name', <identifier>)' method
	popuplib.send('welcome', event_var['userid'])

Tutorial 06
Creating a simple popup menu

import es, popuplib

def load():
	# here we are creating a weapon menu.
	# create them menu using the method '.easymenu('name', '_popup_choice', <function name of the menu selection>)
	popup = popuplib.easymenu('examplemenu', '_popup_choice', menu)
	# give the popup a tilte using '.settitle('')'
	popup.settitle('Pick a weapon:')
	# create a list of menu items, there is no limit
	# the syntax of this is: var = {'item1', 'item2', ...}
	weapons = ('AWP', 'AK47', 'M4A1')
	# place each menu item in the menu
	# we use the 'for' loop here which names runs and names each item 'c'
	for c in weapons:
		# add the items to the menu using '.addoption()'
		popup.addoption(c, c)
	# define the name of the function controlling the menu selection
	popup.menuselect = menu

def unload():
	popuplib.delete('examplemenu')

# 'def player_spawn(event_var):' is fired every time the player spawns
def player_spawn(event_var):
	popuplib.send('examplemenu', event_var['userid'])

# create the menu selection function as shown below
def menu(userid, choice, popupid):
	# check if the player picks the AWP
	if choice == 'AWP':
		# give the player an AWP
		# here we have to use old ESS code for the command
		# es_xgive gives an entity to a player
		# its syntax: es_xgive <identifier> <entity>
		es.server.cmd('es_xgive %s weapon_awp' % userid)
	# check if the player picked the ak47
	elif choice == 'AK47':
		# give the player an ak47
		es.server.cmd('es_xgive %s weapon_ak47' % userid)
	# check if the player picked the m4
	elif choice == 'M4A1':
		# give the player and m4
		es.server.cmd('es_xgive %s weapon_m4a1' % userid)
	# else if the player picked none of the weapons
	else:
		# tell the player he got no weapon
		es.tell('no weapons for you...')

Tutorial 07
Select a random player and give them a weapon

# here we need to include a new module: random
# random... guess what that does
import es, random, playerlib

def player_spawn(event_var):
	# get a random player who is alive and store his userid in the variable 'player'
	# for this we user random method '.choice' to pick from a list of userids made with the playerlib method '.getUseridList(<identifier>)'
	player = random.choice(playerlib.getUseridList('#alive'))
	# give the player an awp
	es.server.cmd('es_xgive %s weapon_awp' % player)

Tutorial 08
Make a chat command line appear in the center of the HUD for 2 sec

# for making delays in ESPy we need to include the module gamethread
import es, gamethread

def player_say(event_var):
	# store the text typed in the variable 'text'
	text = event_var['text']
	# check if the text in lowercase begins with '!centerchat '
	# .lower() and .startswith() are methods build into python
	if text.lower().startswih('!centerchat '):
		# store the text without the '!centerchat ' and in caps in the variable final_text
		# .lstrip() and .upper() are methods build into python
		final_text = text.lstrip('!centerchat ').upper()
		# print the text to the center of the screen
		# es.centerms is used for this and its syntax is: es.centermsg('text')
		es.centermsg("%s" %final_text)
		# now we want it to stay there for 2 sec so we use the gamethread method '.delayed' for this
		# its syntax is: gamethread.delayed(<time in sec>, <command>)
		gamethread.delayed(1, es.centermsg("%s" % final_text))

Tutorial 09
Use a chat command to kick the player, you are looking at

import es, playerlib

def player_say(event_var):
	# check if the text typed was '!kick'
	if event_var['text'] == '!kick':
		# for est_ commands which return something we need to make a server variable for storing the return in, using es.ServerVar
		# its syntax is: es.ServerVar('name').set(0)
		es.ServerVar('target_temp').set(0)
		# now when we have a place to store the return we can get the userid, est_GetViewPlayer is used for this
		# est_GetViewPlayer syntax is: est_GetViewPlayer <the userid looking> <the userid being looked at>
		es.server.cmd("est_GetViewPlayer %s target_temp" % event_var['userid'])
		# now place the server variable into a new variable
		# we use the int() to make sure its a number we are getting
		target = int(es.ServerVar('target_temp'))
		# check if there is a target
		# if there is none the return will be 0
		if target != 0:
			# kick the player using es.ForceServerCommand()
			# its syntax is: es.ForceServerCommand(<command>) 
			es.ForceServerCommand("kickid %s Too bad, I saw you" % target)

Tutorial 10
Make an attraction hook

import es

def player_say(event_var):
	# check if the text was '!hook'
	if event_var['text'] == '!hook':
		# as we have to get 3 return values from an est_ command we will make 3 server variables to store the returns
		# server variable for the X coordinate
		es.ServerVar('ap_x').set(0)
		# server variable for the Y coordinate
		es.ServerVar('ap_y').set(0)
		# server variable for the Z coordinate
		es.ServerVar('ap_z').set(0)
		# now when we have them we can use the command est_GetViewCoord to get the coordinats
		# its syntax is: est_GetViewCoord <identifier> <x> <y> <z>
		es.server.cmd("est_GetViewCoord %s ap_x ap_y ap_z" % event_var['userid'])
		# now store the X Y and Z coordinates in new variables, again using int() to make sure its a number we get
		# store ap_x in apf_x
		apf_x = int(es.ServerVar('ap_x'))
		# store ap_y in apf_y
		apf_y = int(es.ServerVar('ap_y'))
		# store ap_z in apf_z
		apf_z = int(es.ServerVar('ap_z'))
		# finally use the command est_PushTo to make the player come closer to the point he was looking at
		# the est_PushTo syntax is: est_PushTo <identifier> <x> <y> <z> <force>
		es.server.cmd("est_PushTo %s %s %s %s 2" % (event_var['userid'], apf_x, apf_y, apf_z))

Tutorial 11
Making a simple cfg file and addoninfo

# to make a config file we need to include cfglib
import es, cfglib

# first lets type some addon info which can be used later in scripts
# to make less typing use 'info = es.AddonInfo()'
info = es.AddonInfo() 
# set the addon name
info.name        = "Tutorial 11" 
# set the addon version
info.version     = "Version 1.0"
# set the addon author
info.author      = "Svendy"
# set a referral / discussion link to a topic about the script
info.url         = "www.steamgamers.com"

# now for creating the config file
# for less typing do 'config = cfglib.AddonCFG(es.getAddonPath('<addon name>') + '/<cfg name>.cfg')
config = cfglib.AddonCFG(es.getAddonPath('tutorial_11') + '/tutorial_11.cfg')
# make a line of text independent form all variables
config.text("CONFIG")
# create a variable using the method '.cvar()'
# its syntax is: variable_name_in_script = config.cvar('variable_name', "value", 'description')
var1 = config.cvar('var1', "value", 'description')
var2 = config.cvar('var2', "value", 'description')
# write the config file using '.write'
config.write()

def load():
	# execute the config when the addon is loaded
	config.execute()

Tutorial 12
More string manipulation

import es

def player_say(event_var):
	# for less typing do 'userid = str(event_var['userid'])'
	userid = str(event_var['userid'])
	# store the text in the variable 'text'
	text = event_var['text']
	# check if the text in lowercase is 'hello'
	if text.lower() == 'hello':
		# say hello to the user
		es.tell(userid, "hello to you too!")
	# check if the text in uppercase is 'HEY'
	elif text.upper() == 'HEY':
		# say hey to the user
		es.tell(userid, "HEY BRO!")
	# check if the text in lowercase and with a first capital letter is 'Bye'
	elif text.lower().capitalize() == 'Bye':
		# say goodbye to the user
		es.tell(userid, "It was nice to see you")
	# check if the text stats with a space
	elif text.startswith(' '):
		# store the text without the first space in the variable final_text
		final_text = text.lstrip(' ')
		# tell the user the first space has been removed
		es.tell(userid, "The first ' ' has been removed and the text is now:")
		# show to user the text without the first space
		es.tell(userid, "%s" % final_text)
	# check if the text ends with a space
	elif text.endswith(' '):
		# store the text without the last space in the variable final_text
		final_text = text.rstrip(' ')
		# tell the user the last space has been removed
		es.tell(userid, "The last ' ' has been removed and the text is now:")
		# show to user the text without the last space
		es.tell(userid, "%s" % final_text)

I hope you can use them :P