eudtrg API Reference¶

This is eudtrg API Reference. API Reference aims to hold any information needed to use eudtrg properly. If you think that this reference lacks essential information, is too vague, is written in bad grammar, or lacks anything, feel free to contact the author using whyask37@gmail.com.

Expressions¶

Expression is a basic calculation unit of eudtrg. Expression mean ‘Object that can be evaluated to some number’.

Base classes¶

class eudtrg.Expr¶

Expression class. Handle expressions with unknown variables. Example:

a = Forward() # some unknown variable
b = Trigger() # some unknown variable
    # b's value is determined with a call of SaveMap()

c = a + 5 - b # a + 5 - b is an expression with unknown variable.

# since a, b is undetermined yet, c needs to store expression tree of
# 'a + 5 - b', such as in form of (- (+ a 5) b). Expr class can be used
# to store such expressions.

Expr class supports basic arithmetic operators: addition, subtraction, muliplication, and division. Derived class should implement following two methods.

GetDependencyList : List of other expression required for evaluation of the expression. Circular dependency are supported.
EvalImpl : Calculate value of the expression. Evaluate() caches result of EvalImpl, so you should override EvalImpl method instead of Evaluate.

EvalImpl()¶

Returns:	What the object should be evaluated to. For example,

EUDObject returns the data’s address in Starcraft Memory by default. Type of returned object should be one of int, eudtrg.RelocatableInt, or one having Evaluate method.

Evaluate()¶

Returns:	Cached value of EvalImpl.

Evaluate function caches and returns the value of EvalImpl. cache token expires or no values were cached before, Evaluate recaches its value by calling EvalImpl. Cache expires with a call of SaveMap.

GetDependencyList()¶

Raises NotImplementedError:
Returns:	List of Expr instances self depends on.
	Derived class have not overridden this method.

class eudtrg.EUDObject¶

Base class for uploadable objects. Uploadable objects objects having data to be inserted into SC Memory. Every EUDObject corresponds to one memory chunk inside SC Memory. EUDObject creates data to put inside memory chunk.

For example, every trigger in Starcraft is just a 2408byte memory chunk. eudtrg.Trigger refers to that memory chunk, and can create 2408 byte data to put inside it.

EvalImpl()¶

Overrides eudtrg.Expr.EvalImpl() .

Returns:	What this object should evaluate to. Default: Address of object.

GetDataSize()¶

Returns:	Size of data inside SC Memory. Default: 0

GetDependencyList()¶

Overrides eudtrg.Expr.GetDependencyList() .

Returns:	List of Expr instances this object depends on. Default: Empty list.

ResetAddress()¶: Reset object address. Called after payload is successfully injected.

SetAddress(address)¶: Called by eudtrg when address of object is fixed. You won’t need to override this function.

WritePayload(emitbuffer)¶

Writes payload(data) to buffer. Users may use:

emitbuffer.EmitByte(b) : Emit 1 byte(b) to buffer. b should be const.

emitbuffer.EmitWord(w) : Emit 1 word(w) to buffer. w should be const.

emitbuffer.EmitDword(dw) : Emit 1 dword(dw) to buffer. Dword should be constant or should be placed in 4byte boundary : bytes multiple of 4 were emitted before EmitDword() call.

emitbuffer is always aligned to 4byte boundary when WritePayload is called.

Parameters:	emitbuffer – Output buffer. Write payload here.

Basic objects¶

class eudtrg.Forward¶

Forward declaration for expressions. Example:

b = Forward() # Forward declaration
a = Trigger( nextptr = b ) # b is defined here, so no error occurs.
b << Trigger( nextptr = a ) # put in value later.

Forward() class can be assigned a value only once.

Assign(item)¶

Assign expression to self. The object will evaluate to assigned expressions afterwards.

Raises AssertionError:
	Forward has already been assigned. Non-expression types are being assigned into.

EvalImpl()¶

Raises AssertionError:
	Forward hasn’t been assigned to any values by `Assign()`.

class eudtrg.Db(content)¶: Db object inserts binary data into starcraft memory. Db object evaluates to address where bytes are stored.

Triggers¶

Trigger defines map logic.

Functions/Classes on trigger¶

class eudtrg.Trigger(nextptr=None, conditions=, []actions=, []preserved=True)¶

Object representing trigger. Trigger has following fields

nextptr : Pointer to next executed trigger.
conditions : Conditions. Trigger executes if every conditions are met.
actions : Actions. Actions are executed in sequential order.

class eudtrg.Condition(locid, player, amount, unitid, comparison, condtype, restype, flags)¶

Condition class.

Memory layout:

Offset Field name Position EPD Player

+00 locid dword0 EPD(cond)+0

+04 player dword1 EPD(cond)+1

+08 amount dword2 EPD(cond)+2

+0C unitid dword3 EPD(cond)+3

+0E comparison

+0F condtype

+10 restype dword4 EPD(cond)+4

+11 flags

+12 internal[2]

class eudtrg.Action(locid1, strid, wavid, time, player1, player2, unitid, acttype, amount, flags)¶

Action class.

Memory layout.

Offset Field Name Position EPD Player

+00 locid1 dword0 EPD(act)+0

+04 strid dword1 EPD(act)+1

+08 wavid dword2 EPD(act)+2

+0C time dword3 EPD(act)+3

+10 player1 dword4 EPD(act)+4

+14 player2 dword5 EPD(act)+5

+18 unitid dword6 EPD(act)+6

+1A acttype

+1B amount

+1C flags dword7 EPD(act)+7

+1D internal[3]

eudtrg.Disabled(item)¶

Make condition/action disabled. >>> Disabled(SetDeaths(Player1, SetTo, 1234, ‘Terran Marine’))

Parameters:	item – Condition/Action to disable
Returns:	Disabled condition/action.

class eudtrg.NextTrigger¶: Create reference to next declared trigger.

Trigger scope¶

Trigger scopes are used to specify scoping into triggers. Scopes groups triggers together. Triggers in the same scope are eligable for `nextptr auto linking`_.

eudtrg.PushTriggerScope()¶

Creates trigger scope. Triggers inside a scope is isolated from outside. Triggers from different scope won’t have their nextptr linked implicitly. You can still link triggers in other scopes by setting nextptr explicitly. This function is used in conjunction with PopTriggerScope().

example

a = Trigger()
PushTriggerScope() ################
b = Trigger()          isolated
c = Trigger()          isolated
PopTriggerScope()  ################
d = Trigger()

eudtrg.PopTriggerScope()¶: Exits trigger scope. Used in conjunction with PushTriggerScope().

Enumeration parser¶

Enumeration parsers are used to translate human-friendly identifiers to intergal values. Consider following condition:

Bring(Player1, AtLeast, 1, "Terran Marine", "Anywhere")

Each field is parsed by enumeration parser : player field is parsed by eudtrg.ParsePlayer() function, unit field is parsed by eudtrg.ParseUnit() function.

Player1 -> ParsePlayer(Player1) = 0
AtLeast -> ParseComparison(AtLeast) = 0
1
"Terran Marine" -> ParseUnit("Terran Marine") = 0
"Anywhere" -> ParseLocation("Anywhere") = 64

So, the condition is translated as:

Bring(Player1, AtLeast, 1, "Terran Marine", "Anywhere")
Bring(0, 0, 1, 0, 64)
Condition(64, 0, 1, 0, 0, 3, 0, 0)

Enumeration parsers can also be used inside user code. For instance, consider following function changing unit’s graphic to other sprite:

ChangeUnitGraphics(0, 123) # Set Terran Marine's graphics to Sprite #123.

This code can be rewritten to:

ChangeUnitGraphics(ParseUnit("Terran Marine"), 123)

Or even better, ChangeUnitGraphics function can use ParseUnit internally.

eudtrg.ParseSwitchState(s)¶: Convert [Set, Cleared] to [2, 3].

eudtrg.ParseScore(s)¶

Convert score type identifier to number.

Score type	Number
Total	0
Units	1
Buildings	2
UnitsAndBuildings	3
Kills	4
Razings	5
KillsAndRazings	6
Custom	7

eudtrg.ParseComparison(s)¶: Convert [AtLeast, AtMost, Exactly] to number [0, 1, 10].

eudtrg.ParsePropState(s)¶: Convert [Enable, Disable, Toogle] to number [4, 5, 6]

eudtrg.ParseModifier(s)¶: Convert [SetTo, Add, Subtract] to number [7, 8, 9].

eudtrg.ParseOrder(s)¶: Convert [Move, Patrol, Attack] to number [0, 1, 2].

eudtrg.ParseResource(s)¶: Convert [Ore, Gas, OreAndGas] to [0, 1, 2]

eudtrg.ParseCount(s)¶: Convert [All, (other numbers)] to number [0, (as-is)].

eudtrg.ParseAllyStatus(s)¶: Convert [Enemy, Ally, AlliedVictory] to number [0, 1, 2].

eudtrg.ParsePlayer(s)¶

Convert player identifier to corresponding number.

Identifier	Number
P1	0
P2	1
P3	2
P4	3
P5	4
P6	5
P7	6
P8	7
P9	8
P10	9
P11	10
P12	11
Player1	0
Player2	1
Player3	2
Player4	3
Player5	4
Player6	5
Player7	6
Player8	7
Player9	8
Player10	9
Player11	10
Player12	11
CurrentPlayer	13
Foes	14
Allies	15
NeutralPlayers	16
AllPlayers	17
Force1	18
Force2	19
Force3	20
Force4	21
NonAlliedVictoryPlayers	26

eudtrg.ParseAIScript(s)¶: Convert known AI Script to script ID. See eudtrg.RunAIScript() and eudtrg.RunAIScriptAt() for list of AI scripts.

eudtrg.ParseSwitchAction(s)¶: Convert [Set, Clear, Toogle, Random] to [4, 5, 6, 11].

eudtrg.ParseUnit(unitname)¶

Raises RuntimeError:
Parameters:	unitname – Unit name, with or without color characters.
Returns:	Corresponding Unit ID.
	Unit name may match multiple units. There is no corresponding unit to given unit name.

eudtrg.ParseLocation(locname)¶

Raises RuntimeError:
Parameters:	locname – Location name
Returns:	Corresponding location name.
	Location name is ambigious or not defined.

eudtrg.ParseString(string)¶

Raises AssertionError:
Parameters:	string – String
Returns:	Corresponding string number. This function creates new string if there isn’t existing one. String with same contents will have same string ID.
	String table exceeded 65536 bytes.

eudtrg.ParseProperty(prop)¶

Raises AssertionError:
Parameters:	prop (`UnitProperty`) – Unit property
Returns:	Corresponding property ID. Identical Properties will have same property ID.
	More than 64 different properties have been used.

Auxilary library¶

Variable Table¶

class eudtrg.EUDVTable(varn)¶

Full Variable table. EUDVTable stores EUDVariable objects. EUDVTable serves as a key component of trigger programming.

vt = EUDVTable(3) a, b, c = vt.GetVariables() # use a, b, c for further calculations.

EUDVTable is as itself a Trigger, so it can be executed. When EUDVTable is executed, queued calculations are processed. You can queue calculations with EUDVariable.QueueAssignTo() and its family.

GetVariables()¶

Returns:	List of variables inside EUDVTable. If there is only one variable, return it.

class eudtrg.EUDVariable(vartrigger, originvt)¶

Full variable.

AddNumber(number)¶

Parameters:	number – Number to add.
Returns:	`Action` for adding given number to variable.

AtLeast(number)¶

Parameters:	number – Number to compare variable with.
Returns:	`Condition` for checking if the variable is at least given number.

AtMost(number)¶

Parameters:	number – Number to compare variable with.
Returns:	`Condition` for checking if the variable is at most given number.

Exactly(number)¶

Parameters:	number – Number to compare variable with.
Returns:	`Condition` for checking if the variable is at exactly given number.

GetMemoryAddr()¶

Returns:	Memory address where values are stored.

GetVTable()¶

Returns:	Parent EUDVTable.

QueueAddTo(dest)¶

Parameters:

dest –

Where to add variable value to.

EUDVariable : Value of variable is added to dest variable.
EUDLightVariable : Value of variable is added to dest variable.
Expr : Value of variable is added to memory. dest is interpreted as EPD Player.

Returns: List of Action needed for queueing addition.

QueueAssignTo(dest)¶

Parameters:

dest –

Where to assign variable value to.

EUDVariable : Value of variable is assigned to dest variable.
EUDLightVariable : Value of variable is assigned to dest

variable.
Expr : Value of variable is assigned to memory. dest is

interpreted as EPD Player.

Returns: List of Action needed for queueing assignment.

QueueSubtractTo(dest)¶

Parameters:

dest –

Where to subtract variable value to.

EUDVariable : Value of variable is subtracted to dest variable.
EUDLightVariable : Value of variable is subtracted to dest variable.
Expr : Value of variable is subtracted to memory. dest is interpreted as EPD Player.

Returns: List of Action needed for queueing addition.

Warning

Subtraction won’t underflow. Subtracting values with bigger one will yield 0.

SetNumber(number)¶

Parameters:	number – Number to assign.
Returns:	`Action` for assigning given number to variable.

SubtractNumber(number)¶

Parameters:	number – Number to subtract.
Returns:	`Action` for subtracting given number to variable.

Warning

Subtraction won’t underflow. Subtracting values with bigger one will yield 0.

eudtrg.EUDCreateVariables(varn)¶

Create (varn) EUDVariables. Returned variables are not guarranted to be in the same variable table.

Parameters:	varn – Number of EUDVariables to create.
Returns:	List of variables. If varn is 1, then a variable is returned.

eudtrg.SeqCompute(assignpairs)¶

Do multiple assignment/addition/subtraction sequentially.

Parameters:

assignpairs –

List of (dst, src, modtype)

dst : Where to compute
- EUDVariable : Value is stored at variable
- EUDLightVariable : Value is stored at variable
- Expr : Value is stored at memory. Expr is interpreted as
  
  EPD player value.
src : What value to use with computation
- EUDVariable : Value is pulled of from variable.
- Expr : Value is evaluated
modtype : What type of computation to do.
- SetTo : Assignment. dst = src
- Add : Addition. dst += src
- Subtract : Subtraction. dst -= src

Raises AssertionError:

Raises when:

EUDLightVariable is given as src : Light Variable cannot be direcly assigned. They must be read with f_dwread, or be copied to.

Warning

Subtraction won’t underflow. Subtracting values with bigger one will yield 0.

eudtrg.SetVariables(dstlist, srclist, mdtlist=None)¶

Assigns values to variables/memory. This is just a syntax sugar for SeqCompute(). Useful for retrieving function return values after EUD Function call.

SetVariables([unitx, unity], f_dwbreak(position)[0:2])

Parameters:

dstlist –
Nested list of EUDVariable/EUDLightVariable/Expr.
- EUDVariable : Value is stored at variable.
- EUDLightVariable : Value is stored at variable.
- Expr : Value is stored at memory. Expr is interpreted
  
  as EPD Player.
srclist –
Nested list of EUDVariable/Expr.
- EUDVariable : Value is pulled off from variable
- Expr : Value is evaluated.
mdtlist – Nested list of SetTo/Add/Subtract. Default: [SetTo * (Number of varaibles)]

Raises AssertionError:

Raises when:

len(dstlist), len(srclist), len(mdtlist) is different
Type error of arguments.

Warning

Subtraction won’t underflow. Subtracting values with bigger one will yield 0.

eudtrg.VTProc(vt, actions)¶: Shortcut for EUDVTable calculation. VTProc automatically inserts nextptr manipulation triggers, so you wouldn’t have to :param actions: Actions to execute

class eudtrg.EUDLightVariable¶

Light variable. EUDLightVariable occupies only 4 bytes.

AddNumber(number)¶

Parameters:	number – Number to add.
Returns:	`Action` for adding given number to variable.

AtLeast(number)¶

Parameters:	number – Number to compare variable with.
Returns:	`Condition` for checking if the variable is at least given number.

AtMost(number)¶

Parameters:	number – Number to compare variable with.
Returns:	`Condition` for checking if the variable is at most given number.

Exactly(number)¶

Parameters:	number – Number to compare variable with.
Returns:	`Condition` for checking if the variable is at exactly given number.

GetMemoryAddr()¶

Returns:	Memory address where values are stored.

SetNumber(number)¶

Parameters:	number – Number to assign.
Returns:	`Action` for assigning given number to variable.

SubtractNumber(number)¶

Parameters:	number – Number to subtract.
Returns:	`Action` for subtracting given number to variable.

Warning

Subtraction won’t underflow. Subtracting values with bigger one will yield 0.

Common control structures¶

eudtrg.DoActions(actions)¶

Shortcut for creating trigger with only action fields specified.

Parameters:	actions – Trigger actions.

eudtrg.EUDJump(nextptr)¶

Trigger with only nextptr specified. Useful for controlling trigger execution order. Acts as jmp instruction of x86 assembly.

Parameters:	nextptr – Trigger to execute next.

eudtrg.EUDJumpIf(conditions, ontrue)¶

Jump if conditions are met. Two triggers are executed when jumping. If jump conditions are not met, then the following triggers are executed.

Parameters:	conditions – Jump condition. ontrue – Trigger to execute when conditions are met.

eudtrg.EUDJumpIfNot(conditions, onfalse)¶

Jump if conditions are not met. Two triggers are executed when jumping. If jump conditions are met, then the following triggers are executed.

Parameters:	conditions – No jump condition. ontrue – Trigger to execute when conditions are not met.

eudtrg.EUDBranch(conditions, ontrue, onfalse)¶

Branch based on conditions.

Parameters:	conditions – Conditions to check. ontrue – Trigger to execute when conditions are met. onfasle – Trigger to execute when conditions are not met.

eudtrg.EUDFunc(fdecl_func)¶

Generates EUD Function. Usually used as decorators. EUD Function cannot be recursive.

@EUDFunc
def f_add(a, b):
    ret = EUDCreateVariables(1)
    SeqCompute([
        (ret, SetTo, 0),
        (ret, Add, a),
        (ret, Add, b)
    ])

    return ret

EUD function gets several EUDVariables as arguments, but user can use both EUDVariable and Expr for calling function.

a,b = EUDCreateVariable(2)
c = Trigger()
d = c_int

f_mul(a,b) # ok
f_mul(10, b) # ok. 10 can be implicitly converted to Expr.
f_mul(10, 20) # ok.
f_mul(a, c) # ok. Trigger is type of expression. In this case, address
    # of trigger will be passed to f_mul.
f_mul(a, d) # Error. c_int is neither EUDVariable nor Expr.

EUD Function may return several return values. Return values are overwritten after every function call, so users should store it with SetVariables() or SeqCompute() if they need it.

SeqCompute(local_variable, f_function()) # store return value

f_function() # local_variable still presists its value.

If returned values won’t be used after another function call, users don’t have to store it.

var = f_function()

f_function() # var is overwritten now.

Parameters:	fdecl_func – Function to be converted into EUD function. fdecl_func recieves several EUDVariable and should return single/list of EUDVariable.

eudtrg.InitPlayerSwitch(playerroots)¶

Override default behavior of SaveMap() and set starting trigger for all players.

Parameters:	playerroots – Starting trigger for each players. (List of 8 elements) Starting trigger may be None if the player won’t execute any trigger.
Returns:	Starting trigger for InitPlayerSwitch to work.

Warning

You should call InitPlayerSwitch at most once.

Common objects¶

String table¶

class eudtrg.EUDTbl¶

Custom string table.

SetAsDefault()¶: Set default string table to self. All strings used by DisplayText will be forwarded to current string table

Warning

Always call f_initeudtbl() before using this function. Always call f_reseteudtbl() after using this function.

StringIndex(string)¶: Get string index of certain string inside string table. :param string: String to get index. :returns: String index. :raises AssertionError: String table exceeds 65536 bytes.

eudtrg.f_reseteudtbl()¶: Restore string table address. If you used custom string table, then you should call this function before trigger loop ends.

eudtrg.f_initeudtbl()¶: Backup original string table address.

Custom graphic (.GRP)¶

class eudtrg.EUDGrp(content)¶: Object wrapper for GRP

Utility functions¶

eudtrg.EPD(offset)¶: Offset to EPD player.

Basic EUD Functions¶

Arithmetics¶

eudtrg.f_mul(a, b)¶

Returns:	a * b

eudtrg.f_div(a, b)¶

Returns:	a//b, a % b

Memory I/O¶

eudtrg.f_epd(addr)¶

Convert address to EPD Player value. Use EPD() instead to convert Expr to EPD player value.

Parameters:	addr – Address to convert.
Returns:	EPD player corresponding to given address.

eudtrg.f_dwread(targetplayer)¶: Read dword from memory. This function can read any memory with read access. :param targetplayer: EPD Player for address to read. :returns: Memory content.

eudtrg.f_dwwrite(targetplayer, value)¶

Writes value to specified address.

Parameters:	targetplayer – EPD Player of address to write value. value – Value to write.

eudtrg.f_dwbreak(number)¶

Break dword into words & dwords.

Parameters: number – Number to break.

Returns:

w[0], w[1], b[0], b[1], b[2], b[3]

union {: DWORD number; WORD w[2]; BYTE b[4];

}

eudtrg.f_repmovsd(dstepdp, srcepdp, copydwn)¶

rep movsd equivilant in eudtrg. Copy dwords. Faster than f_memcpy.

Parameters:	dstepdp – EPD Player for destination. srcepdp – EPD Player for source. copydwn – Count of dwords to copy.

eudtrg.f_memcpy(dst, src, copylen)¶

memcpy equivilant in eudtrg. Copy bytes.

Parameters:	dst – Destination address. (Not EPD Player) src – Source address. (Not EPD Player) copylen – Count of bytes to copy.

eudtrg.f_strcpy(dst, src)¶

strcpy equivilant in eudtrg. Copy C-style string.

Parameters:	dst – Destination address. (Not EPD Player) src – Source address. (Not EPD Player)

Map I/O Functions¶

eudtrg.SaveMap(fname, roots)¶

Save template map with EUDObjects & various files.

Parameters:	root – Starting trigger for each player. List of length 8. additionalfiles – List of (MPQ Filename, bytes) to be inserted into map MPQ. If different contents share the same MPQ filename, function will raise RuntimeError.

eudtrg.LoadMap(fname)¶

Load template map and read various data from it.

Parameters:	fname – Path to input map.

eudtrg API Reference¶

Expressions¶

Base classes¶

Basic objects¶

Triggers¶

Functions/Classes on trigger¶

Trigger scope¶

Enumeration parser¶

Auxilary library¶

Variable Table¶

Common control structures¶

Common objects¶

String table¶

Custom graphic (.GRP)¶

Utility functions¶

Basic EUD Functions¶

Arithmetics¶

Memory I/O¶

Map I/O Functions¶

Table Of Contents

This Page

Offset	Field name	Position	EPD Player
+00	locid	dword0	EPD(cond)+0
+04	player	dword1	EPD(cond)+1
+08	amount	dword2	EPD(cond)+2
+0C	unitid	dword3	EPD(cond)+3
+0E	comparison
+0F	condtype
+10	restype	dword4	EPD(cond)+4
+11	flags
+12	internal[2]

Offset	Field Name	Position	EPD Player
+00	locid1	dword0	EPD(act)+0
+04	strid	dword1	EPD(act)+1
+08	wavid	dword2	EPD(act)+2
+0C	time	dword3	EPD(act)+3
+10	player1	dword4	EPD(act)+4
+14	player2	dword5	EPD(act)+5
+18	unitid	dword6	EPD(act)+6
+1A	acttype
+1B	amount
+1C	flags	dword7	EPD(act)+7
+1D	internal[3]

Navigation

eudtrg API Reference¶

Expressions¶

Base classes¶

Basic objects¶

Triggers¶

Functions/Classes on trigger¶

Trigger scope¶

Enumeration parser¶

Auxilary library¶

Variable Table¶

Common control structures¶

Common objects¶

String table¶

Custom graphic (.GRP)¶

Utility functions¶

Basic EUD Functions¶

Arithmetics¶

Memory I/O¶

Map I/O Functions¶

Table Of Contents

This Page

Quick search

Navigation