EGUI Tutorial (1.3)

[Dark_Dragon]

EGUI Tutorial (1.3)

This tutorial was written by Deuterium and edited by Dark Dragon

Introduction

To start with, EGUI (or Extra Graphic User Interface) is basically an improved version of Blizzard's GUI by Dark_Dragon. It fixes various bugs present in Blizzard's GUI and adds certain important functions - such as Remove Location - and certain types such as GroupExtra (which is a leakless and fast type of groups).

One of the unique things about EGUI is that it comes with JNGPS (Jass New Gen Pack Special also by Dark_Dragon - an improved version of Jass New Gen Pack), thus allowing GUI users now to get the benefit of some vJass options and functions.

One very important and essential feature of EGUI is that it can be enabled and disabled quite fast. However, EGUI only works on Warcraft III versions released after the version 1.24.

What's more, to enable EGUI, a custom script must be called for example at map intialization:

Example

• Custom script: Enable EGUI[/hidden]

I - Events

1. Destructible

a. Any Destructible Dies: an event that fires when any destructible dies. Dying destructible is referred to through Event Response - Dying Destructible.

2. Game

a. Event Preload: loads a given file during loadscreen to prevent lag due to in-game loading

3. Item Config

a. Any Item Fused Event: an event that fires when an item is fused/combined. Unit receiving the item is referred to through Event Response - Triggering Unit and combined item through Event Response - Fused Item.

4. Player

a. Keyboard Event (Any): an event that fires when any keyboard arrow event is triggered (either pressed or held, depending on the condition picked by the user).

5. Trackable

a. Trackable Event: an event that fires when a trackable is either is selected or has the mouse over it (depending on the users choice).

6. Unit

a. Any Unit Event: an event that fires when any unit does the action selected by the user. Much faster than Generic Unit Event and fully leakless.

b. Any Unit Damaged Even: an event that fires whenever any unit is damaged.

c. Unit Enters Map Area: whenever unit enters playable map area this trigger will execute, fully leakless and faster than 'Unit Enters Region'

d. Unit Leaves Map Area: whenever unit leaves playable map area this trigger will execute, fully leakless and faster than 'Unit Leaves Region'

7. Widget

a. Widget Dies Event: runs when given widget dies. To get widget which died use Event Response - Trigger Widget

II - Conditions

a. Arrow Key Comparsion: use in event Player - Keyboard Event (Any) to detect which arrow is pressed/released

b. Key Type Comparsion: use in event Player - Keyboard Event (Any) to detect is arrow pressed/released

c. Trackable Compare: allows the user to compare trackables as a condition.

d. XOr: returns exclusive or (xor) from given conditions, xor returns true only when one of conditions is true

e. And 3x: allows the user to compare three conditions seperated by and.

f. Or 3x: allows the user to compare three conditions seperated by or.

g. Bit to Boolean: allows the user to convert a bit to boolean, where 1 stand for true and zero for false.

h. Custom Script: allows a Jass code to be a condition.


There also are new conditions under certain comparison sections; for example under the Boolean Comparison section there's the bugless Is Unit Dead comparison, Is Unit Invunerable, Is Terrain Water, and such...

III - Actions

1. General

a. Custom Script: added new presets

• Enable EGUI - Will include custom EGUI functions
• Enable Anti-BJ - Will optimize your script, requires cJass to be enabled
• No Script - Any next code will be ignored (wont exist)
• End No Script - Ends no script action, meaning code (will exist)
• while - Starts loop
• endwhile - Ends started loop
• break - exits "while" loop or "for" loop
• create local index - creates an index to be used as an array index in order to make your "spell/system" MUI.
• set bj_wantDestroyGroup = true - set bj_wantDestroyGroup = true - Destroys the first Unit Group used after this action automatically

b. Sleep: leakless Wait with high functionality and precision. Far better then Blizzard's own Wait.

2. Cluster

A Cluster is a type which can store a set of Special Effects. This would allow the user to set up various special effects together - for instance, making a missile consisting of two different special effects - and destroy them easily without leaving any leaks.

To make it clear, a cluster is basically the imitation of a group; however, instead of adding units or players to the group, special effects are added.

Last created clusters are not accessible via Last created special effect but through Last created cluster.

Clusters must be destroyed to avoid leaking!

a. Create Cluster: creates an empty cluster in which special effects could be stored.

b. Add Effect To Cluster: enables the user to add a certain special effect to the cluster which would then show in-game just like any other special effect.

c. Cluster Add Effect At Point: adds a new effect to the cluster at a certain point.

d. Cluster Add Effect On Widget: adds a new effect to the cluster on a certain attachment point on a widget.

e. Destroy Cluster: destroys a defined cluster instantly and all effects inside.

f. Destroy Cluster Timed: destroys a defined cluster and effects inside after certain seconds.

3. - Countdown Timer

a. Start Timer (Advanced): runs a timer with the option of being repeating or one-shot and with the ability of specifying the trigger it executes every time it expires. The timer also holds a private value of it's own to allow the user to access it only when needed.

b. Destroy Timer: timer which gets destroyed cant be used again.

4. - Group Extra

Group Extra is actually one of the most unique features of EGUI. It allows the GUI user to create leakless and faster groups then Blizzard's own Unit Group.

Very simple to use as its actions are similar to those of Unit Group with some extra and useful new actions.

In order to loop through all units in Group Extra you need to use "For" loop and access unit by index from the Group Extra

Group Extra needs to be destroyed after it's used to avoid leaks.

a. Create Group Extra: creates an empty group extra.

b. Add Unit: adds a unit to a previously created group extra.

c. Remove Unit: removes a unit from a certain group extra.

d. Set Group Size: sets the maximum size of a group extra, meaning that no more than the defined number (i.e. size) of units can be in this group.

e. Set Group User Value: gives a group extra a private value, allowing the user to access it only when needed.

f. Free Group Extra: removes all units from a given group extra.

g. Destroy Group Extra: destroys a group extra instantly.

h. Destroy Group Extra Timed: destroys a group extra and removes all units inside from game after certain seconds.

5. Item Config

One very nice feature - in my opinion - of EGUI is the Item Config (i.e. configuration). It allows the user to create item recipes in a very simple approach.

Item Config is referred to through Last created item config.

All Item Config actions must be called in trigger which has event "Map Initialization"

a. Create Item Config: creates a new item configuration which could hold up to 6 items to be fused.

b. Set Model File: determines the model file of the effect which occurs upon the fusion of the recipe.

c. Enable Fuse Sound: enables the occurrence of a sound upon the fusion of a recipe.

d. Enable Item Stack: allows items with charges to stack.

e. Add Request Item: adds an item needed to complete a recipe to a certain Item Config.

f. Set Central Type: determines the item which all the recipe would fuse into.

6. Lightning

EGUI comes with few custom lightning functions.

a. Create Lightning Effect (Z): allows user to create lightning at 3D point

b. Connect Units With Lightning will create lightning effect which connects two given units for given amount of time

7. Point

These are few actions related to the X-Y coordinates point.

Points must be removed after being used to avoid leaking.

a. Move Point: moves a certain point to the newly defined coordinates.

b. Move Point to Widget: moves a certain point to the location of a specified widget.

c. Store Point: stores a point into an buffer on specific index. The index values may range from 1 to 8191.

d. Buffer Clear: removes all points inside a buffer.

e. Remove Point: the GUI form of the well know custom script: call RemoveLocation(). This removes the point instantly.

8. Region

a. Remove Region removes given region from the game

9. Static Variable

A Static Variable is another type of variables. Commonly to a global variable, it stores information about a certain defined type. However, the unique thing about static variables is that their only accessible in the trigger where they are created.

a. New Static: declares a new static variable which would be only accessible in the trigger which it gets created. This action requires a custom script in the following form: <type> <variable list>

A table for the list of types (as they should be written in custom scripts) would be:

boolean

cluster

destructable

floatingtext

item

lightning

player

playergroup

point

real

region

sound

specialeffect

string

timer

unit

groupextra

visibilitymodifier

widget

Take this as a simple example of how New Static is used:

Example

• Static Variable - static integer i = 5[/hidden]

Basically, this sets an integer i to 5.

This would be another example consisting of an arrayed variable. To make an integer arrayed, just insert [] after the variable name. This would create a variable with maximum array size:

Example

• Static Variable - static real r[][/hidden]

This creates an arrayed real variable r. Arrayed variables can't have initial values; however, non-arrayed variables can.

If you want to restrict the array size to a certain value, just insert a number in the array of the variable being created:

Example

• Static Variable - static unit u[3][/hidden]

This creates a unit variable with maximum array size of 3.

One nice feature about New Static, is that you can create multiple variables of the same type in one line by just inserting a comma between each variable:

Example

• Static Variable - static integer i = 20, k, m[10], n[][/hidden]

This creates a non-arrayed integer i of value 20, a non-arrayed integer k of no value, an arrayed integer m whose maximum array is 10, and an arrayed integer n with no defined maximum array.

10. Trackables

Trackables are models in-game which allow you to detect mouse events.

a. Create Trackable: creates an new trackable in-game.

11. Trigger

a. Run Timed (Conditional): runs trigger correctly after given (x) seconds

b. Delete Any Unit Damaged Event: if the specific trigger has previously registered the event 'Any Unit Takes Damaged', this action will clear that event.

c. Delete Any Destructable Death Event: if the specific trigger has previously registered the event 'Any Destructable Dies', this action will clear that event.

d. Delete Any Item Fused Event: if the specific trigger has previously registered the event 'Any Item Fused', this action will clear that event.

e. Destroy Trigger: given trigger will be destroyed, meaning it will never be executed again. All static variables in this trigger will be destroyed as well.

12. Unit

a. Create Unit: a faster and fully leakless approach to create one unit. Refer to this with Last created unit.

b. Create Dummy: creates a dummy unit with no visible model and with an expiry timer. If timer is set to 0, then the dummy would have no expiry timer. Refer to this with Last created unit.

c. Set Unit Z: sets the height of the unit to a given value.

d. Enable Unit Revive: enables unit-revive for a given player. If the delay timer set for unit revival is equal to -1.00, then that certain type of units won't have revive enabled. This must be called at Map Initialization.

e. Set State (Value): allows changing the following states:

• Life
• Max life
• Mana
• Max mana

f. Stun Unit: stuns a certain unit for a given time.

g. Slow Unit: slows a certain unit for a given time.

h. Damage Over Time: damages a unit over time every given seconds. The user has an option of choosing an effect which will appear every instance the target is damaged.

i. Damage Area: damages units in a given area matching the given conditions.

j. Knockback Unit: knockbacks a unit for a certain time at a certain speed and vector shape.

k. Fade Unit: changes the unit's transparency over time.

13. Widget:

A widget is basically any in-game entity which has life. For instance, a unit is a widget.

a. Set Widget Life: sets the life of a widget to a new value.

b. Widget Drop Item: upon death, the given widget will drop a certain item.

IV - Return Values

1. Static Variables

a. Read Static: exists for every type, simply returns stored data...

b. Conversion - Variable Array: use this function for static array variables

2. Boolean

a. Percentage Chance: has n% chance to trigger the spell/system

b. Destructable Is Tree: returns true if given destructable is tree

c. Point Is Water: returns true if given point (x, y) is water

d. Group Extra Has Unit: returns true if given unit is in given group

e. Group Extra Is Empty: returns true if given group has no units

f. Group Extra Is Dead: returns true if all units inside group are dead

g. Is Trackable Select Event: if trigger has events trackable select and mouse over events use this to detect which one was triggerd

h. Safe Is Unit Dead: quickly checks is unit dead, returns true if unit is dead

i. Is Unit Invulnerable: returns true if unit is invulnerable

j. Is Melee Damage: use in event "Any Unit Takes Damage" to detect is taken damage melee or spell type. Returns true if its melee.

3. Arithmetic

Arithmetic is an new way for calculating integer and real numbers.

a. Operators:

• (+) - Add
• (-) - Substract
• (x) - Multiply
• (/) - Divide
• (^) - Power
• (%) - Modulo
• (<) - Minimum
• (>) - Maximum
• (?) - Random
• - Tertiary Op

Tertiary Op is much better then if / then / else

Tertiary Op Example

With tertiary op

• Set Damage = (85.00 (:(lvl == 1):) 125.00 (:(lvl != 3):) 200.00)

Without tertiary op

• If (All Conditions are True) then do (Then Actions) else do (Else Actions)
  • If - Conditions
    • (lvl == 1)
  • Then - Actions
    • Set Damage = 85.00
  • Else - Actions
    • If (All Conditions are True) then do (Then Actions) else do (Else Actions)
      • If - Conditions
        • (lvl == 2)
      • Then - Actions
        • Set Damage = 125.00
      • Else - Actions
        • Set Damage = 200.00

b. Arithmetic: calculates given two numbers, allows new operators

c. Arithmetic 3x: calculates given three numbers, allows new operators

d. Arithmetic (Simple): calculates given two numbers, does not allow new operators

4. Integer

a. Array 2D: 2D array, use this as 1D index

b. Timer Value: in trigger which was executed by "Start Timer (Advanced)" this will return timers private value

c. Get Group User Value: returns stored value on given group

d. Count Units In Group Extra: number of units in group

e. Limits: gives limits to given number of being min and max

f. Log: integer logarithm, 100% precious as integer can go

5. Real

a. For Loop Real A: same as integer A but already converted to real

b. For Loop Real B: same as integer B but already converted to real

c. Z Of Point: returns terrain height

d. X Of Unit: returns x of unit

e. Y Of Unit: returns y of unit

f. Distance Between Widgets: calculates distance

g. Angle Between Widgets: calculates angle in degrees

h. Limits: gives limits to real

i. Log: calculates real logarithm

j. Parabolic Height: returns height at given distance on defined parabola

k. Trackabke Facing: returns facing of trackable in degrees

l. Widget Life/X/Y: returns widgets life/x/y

6. Unit

a. Unit In Group Extra: returns unit from given group at given index. index goes from 1 to n units in group extra.

b. Random Unit From Group Extra: returns random unit from given group.

If you have any more questions, requests or suggestions feel free to comment!

Greets from Deuterium and Dark Dragon!

 

[aznricepuff]

This is a tutorial section, not a section to place manuals in. And btw I think some of these extra features are dubious at best (the most striking is for loops with reals...). Graveyarded.