EEex v0.6.0-alpha

Changelog:

New Opcodes =>

• Opcode #403 (ScreenEffects):

  Whenever an effect is being added to the target creature a Lua function specified by the resource key is called. Maximum function name length is 8, and function names must be completely upper-case. The Lua function's signature can be seen in the following header:

  function B3BLOCKD(originatingEffectData, effectData, creatureData)

  A return value of true blocks the effect from applying. Note: the immunity function "sees" effects after they have passed their probability roll, but before any saving throws have been made against said effect / other immunity mechanisms have taken place. The originating effect is passed via the immunity function's first Lua param.

• Opcode #404 (OverrideButtonType):

  Alters a specific actionbar button on the target creature:
  Param1 = Type to override
  Param2 = Override with type

  Known values for both parameters match what is defined by EEex_ACTIONBAR_TYPE in M__EEex.lua:

  2 BARD_SONG
  3 CAST_SPELL
  4 FIND_TRAPS
  5 TALK
  7 GUARD
  8 ATTACK
  10 SPECIAL_ABILITIES
  11 STEALTH
  12 THIEVING
  13 TURN_UNDEAD
  14 USE_ITEM
  15 STOP
  21 QUICK_ITEM_1
  22 QUICK_ITEM_2
  23 QUICK_ITEM_3
  24 QUICK_SPELL_1
  25 QUICK_SPELL_2
  26 QUICK_SPELL_3
  27 QUICK_WEAPON_1
  28 QUICK_WEAPON_2
  29 QUICK_WEAPON_3
  30 QUICK_WEAPON_4
  100 NONE
  

• Opcode #405 (OverrideButtonIndex):

  Alters a specific actionbar button on the target creature:
  Param1 = Actionbar index to override
  Param2 = Override with type
  Special = Actionbar config to match (-1 to match any class home)

  See Opcode #404 for known values of Param2.

Opcode Changes =>

• Opcode #42 and Opcode #62:

  Special field of 1 ignores slot requirement.

• Opcode #319:

  Implemented SPLPROT Modes.

  New Mode (Power) values:
  2 = like mode 1 but parameters use splprot.2da
  3 = like mode 0 but parameters use splprot.2da

  If 'Mode' is set to 2 or 3, then the creature type specified by the 'Stat Type' field will be affected by this opcode. See opcode #324 for more information.

Script Action Changes =>

• EEex_Lua():

  Now runs Lua chunks, (Lua code embedded in the string arg), instead of calling a function.

  The actorID of the executing actor is passed to the chunk via the global EEex_LuaActorID.

Script Trigger Changes =>

• EEex_LuaTrigger():

  Now runs Lua chunks, (see above).

  The actorID of the executing actor is passed to the chunk via the global EEex_LuaTriggerActorID.

  The return value of the trigger is passed back to the engine by setting the global EEex_LuaTrigger before returning from the chunk.

New Modules =>

• B3_CuBar.lua:

  Allows actionbar to be customized in-game. Enable in EEex_INI.lua, and hold shift key while on world screen to use.

• B3_Portr.lua:

  Disables action overlay on party portraits.

Module Changes =>

• B3Hotke.lua:

  Can now cast spells that use an actionbar submenu by using B3Hotkey_CastTwoStep().

Function Changes =>

• C:Eval():

  Can now accept an actorID as the 2nd param.

• EEex_StoreTemplateInstance():

  Takes an additional first param (string) to target a specific menu.

• Memorization retrieval functions now populate name and description data.

Fixes =>

• Most bits utility functions have been reworked / fixed.

• Opcode #42 and Opcode #62 should not ignore slot requirement by default, (see change above).

New Functions =>

• EEex_AddPostResetListener(listener):

  Given listener function is called after an F5 UI reload is executed.

• EEex_AlterActorEffect(actorID, match_table, set_table, multi_match):

  Like the WeiDU ALTER_EFFECT function, except that it alters effects in the middle of the game.

  EEex_AlterActorEffect(actorID, {{"opcode",232},{"parameter2",0},{"resource","SPWI304"}}, {{"resource","SPWI502"}}, 2)

  equals

  LPF ALTER_EFFECT INT_VAR multi_match=2 match_opcode=232 match_parameter2=0 STR_VAR match_resource=~SPWI304~ resource=~SPWI502~ END
  

  Valid field names:

  opcode
  target
  power
  parameter1
  parameter2
  timing
  duration
  probability1
  probability2
  resource
  dicenumber
  dicesize
  savingthrow
  savebonus
  special
  school
  lowestafflevel
  highestafflevel
  resist_dispel
  parameter3
  parameter4
  time_applied
  vvcresource
  resource2
  casterx
  source_x
  castery
  source_y
  targetx
  target_x
  targety
  target_y
  restype
  effsource
  parent_resource
  resource_flags
  impact_projectile
  sourceslot
  effvar
  casterlvl
  internal_flags
  sectype
  source_id
  

• EEex_ApplyEffectToActor(actorID, args):

  Directly applies an effect to an actor based on the args table. Valid arg keys:

  opcode
  target
  power
  parameter1
  parameter2
  timing
  resist_dispel
  duration
  probability1
  probability2
  resource
  dicenumber
  dicesize
  savingthrow
  savebonus
  special
  source_target
  target_x
  target_y
  source_id
  source_x
  source_y
  vvcresource
  resource2
  parent_resource
  resource_flags
  impact_projectile
  source_slot
  casterlvl
  internal_flags
  sectype
  

• EEex_CyclicBound(num, lowerBound, upperBound):

  Sanity function to help work with number ranges that are cyclic, (like actor direction).

  Example:
  EEex_CyclicBound(num, 0, 15)
  defines a range of 0 to 15. num = 16 rolls over to 0, as does num = 32. num = -1 wraps around to 15, as does num = -17.

• EEex_DestroyInjectedTemplate(menuName, templateName, instanceId):

  Destroys an instance injected into a menu via EEex_InjectTemplate().

• EEex_EvalObjectAsActor(object, actorID):

  Evaluates an object pointer, (returned by EEex_ParseObjectString()), as if it was evaluated by the given actor.

• EEex_EvalObjectStringAsActor(string, actorID):

  Evaluates an object string in standard BAF syntax as if it was evaluated by the given actor.

• EEex_GetActionbarButtonFrame(buttonIndex):

  Returns the current frame of the actionbar button at buttonIndex, taking into account the click status.

• EEex_GetActorAnimation(actorID):

  Returns the actor's animation, (as defined in ANIMATE.IDS; stored at offset 0x28 of the .CRE, or optionally overridden by the actor structure at offset 0x30).

• EEex_GetActorAreaRes(actorID):

  Returns the actor's current area resref as a string.

• EEex_GetActorBaseCharisma(actorID):

  Returns the actor's base charisma, (defined at offset 0x23E of the .CRE).

• EEex_GetActorBaseConstitution(actorID):

  Returns the actor's base constitution, (defined at offset 0x23D of the .CRE).

• EEex_GetActorBaseDexterity(actorID):

  Returns the actor's base dexterity, (defined at offset 0x23C of the .CRE).

• EEex_GetActorBaseIntelligence(actorID):

  Returns the actor's base intelligence, (defined at offset 0x23A of the .CRE).

• EEex_GetActorBaseStrength(actorID):

  Returns the actor's base strength, (defined at offset 0x238 of the .CRE).

• EEex_GetActorBaseWisdom(actorID):

  Returns the actor's base wisdom, (defined at offset 0x23B of the .CRE).

• EEex_GetActorClassScript(actorID):

  Returns the actor's class script, (defined at offset 0x250 of the .CRE, or optionally overridden by the actor structure at offset 0x60).

• EEex_GetActorCurrentAction(actorID):

  Returns the ID of the action the actor is currently doing, based on ACTION.IDS.

  For example, if the actor is currently moving to a point, it will return 23 because MoveToPoint() is action 23 in ACTION.IDS.

  If the actor isn't doing anything, it will return 0.

• EEex_GetActorCurrentHP(actorID):

  Returns the actor's current HP, (defined at offset 0x24 of the .CRE).

• EEex_GetActorDefaultScript(actorID):

  Returns the actor's default script resref as a string, (defined at offset 0x268 of the .CRE, or optionally overridden by the actor structure at offset 0x70).

• EEex_GetActorDialogue(actorID):

  Returns the actor's dialogue resref as a string, (defined at offset 0x2CC of the .CRE, or optionally overridden by the actor structure at offset 0x48).

• EEex_GetActorDirection(actorID):

  Returns the actor's direction, (as defined in DIR.IDS; stored at offset 0x34 of the actor structure).

• EEex_GetActorGeneralScript(actorID):

  Returns the actor's general script resref as a string, (defined at offset 0x260 of the .CRE, or optionally overridden by the actor structure at offset 0x58).

• EEex_GetActorIDShare(share):

  Returns the actorID for the given share / creatureData.

• EEex_GetActorModalState(actorID):

  Returns the actor's current modal state, (as defined in MODAL.IDS; stored at offset 0x28 of the global-creature structure).

• EEex_GetActorMovementRate(actorID, adjustForHaste):

  Returns the actor's movement rate. For example, if the actor has an effect (opcode 126 or 176) that sets their movement rate to 180, it will return 180.

  If the actor does not have a movement-modifying effect, it will return the "move_scale" number in the creature's animation INI file.

  If adjustForHaste is true, the movement rate number will be doubled if the actor is hasted, and it will be halved if the actor is slowed.

• EEex_GetActorOverrideScript(actorID):

  Returns the actor's override script resref as a string, (defined at offset 0x248 of the .CRE, or optionally overridden by the actor structure at offset 0x50).

• EEex_GetActorRaceScript(actorID):

  Returns the actor's race script resref as a string, (defined at offset 0x258 of the .CRE, or optionally overridden by the actor structure at offset 0x68).

• EEex_GetActorRequiredDirection(actorID, targetX, targetY):

  Returns the direction, (as defined in DIR.IDS), required for the actor to face the given point.

• EEex_GetActorSpecificsScript(actorID):

  Returns the actor's specifics script resref as a string, (defined at offset 0x78 of the actor structure).

• EEex_GetActorSpellRES(actorID):

  Returns the resref of the spell the actor is either currently casting or is about to cast (waiting for its aura to be cleansed).

  For example, if the actor is casting Fireball, it will return "SPWI304".

  If the actor is not casting a spell, it will return "".

• EEex_GetActorTargetID(actorID):

  Returns the ID of the target of the actor's current action.

  If the actor is not targeting another creature (e.g. if the actor is doing nothing, targeting a point, or targeting a container, door, or trap), then it will return 0.

• EEex_GetImageMasterID(actorID):

  If the actor is an image created by Mislead, Project Image or Simulacrum, this returns the actor ID of the image's master. Otherwise, it returns 0.

• EEex_GetSpellData(resref):

  Gets offset 0x0 of the data for the SPL file. The offsets after that are exactly the same as in a SPL file.

  For example:
  Infinity_DisplayString(EEex_ReadDword(EEex_GetSpellData("SPWI304") + 0x34))
  will print: '3' because offset 0x34 in the SPL file is the spell's level.

  Warning: this will crash if the spell is not in the game.

• EEex_GetSummonerID(actorID):

  If the actor is a summoned creature, this returns the actor ID of its summoner.

  If the actor is not a summoned creature, or if it's an image created by Mislead, Project Image or Simulacrum, this will return 0.

  Note: this will return 0 if the creature had already been summoned before the save was loaded.

• EEex_HasState(actorID, state):

  Returns true if the actor has the specified state, based on the numbers in STATE.IDS.

  For example, if the state parameter is set to 0x8000, it will return true if the actor is hasted or improved hasted, because STATE_HASTE is state 0x8000 in STATE.IDS.

• EEex_InjectTemplate(menuName, templateName, x, y, w, h):

  Exactly the same as Infinity_InstanceAnimation(), but allows said instance to be "injected" into the menu specified.

• EEex_IsActionbarButtonDown(buttonIndex):

  Returns true if the actionbar button at buttonIndex is currently in the process of being clicked.

• EEex_IsActorFacing(sourceID, targetID):

  Returns true if the sourceID actor is facing the exact direction required to face the targetID actor.

• EEex_IsActorInCombat(actorID, includeDeadZone):

  Returns true if the given actor is in combat.

  If includeDeadZone is set to true, the time period will be extended to until the battle music fully fades out.

• EEex_IsImmuneToOpcode(actorID, opcode):

  Returns true if the actor is immune to the specified opcode.

• EEex_IsImmuneToSpellLevel(actorID, level, includeSpellDeflection):

  Returns true if the actor is immune to the specified spell level.

  If includeSpellDeflection is true, it will also return true if the actor has a Spell Deflection, Spell Turning or Spell Trap effect for the specified spell level.

• EEex_IsValidBackstabDirection(attackerID, targetID):

  Returns true if the attackerID actor's direction is sufficient to backstab the targetID actor.

• EEex_IterateActorEffects(actorID, func):

  For each effect on the actor, the function is passed offset 0x0 of the effect data. The offsets in the effect data are the same as the offsets in an EFF file.

  For example, if you do:

  EEex_IterateActorEffects(EEex_GetActorIDCursor(), function(eData)
      local opcode = EEex_ReadDword(eData + 0x10)
      Infinity_DisplayString(opcode)
  end)
  

  It will print the opcode number of each effect on the actor.

• EEex_LoadMenuFile(resref):

  Loads in the given .MENU file as if it were UI.MENU. Note that in order to keep the menu loaded in the event of an F5 UI reload, a post-reset listener must be used to reload the menu manually.

• EEex_ParseObjectString(string):

  Parses the given object string in standard BAF syntax and returns a pointer to the compiled CAIObjectType instance. Use EEex_EvalObjectAsActor() to evaluate the compiled object instance in relation to an actor.

• EEex_ReadSignedWord(address, index):

  Reads a signed 2-byte word at the given address, shifted over by 2*index bytes.

• EEex_ScreenToWorldXY(screenX, screenY):

  Translates the given screenX and screenY into a worldX and worldY. Use EEex_GetTrueMousePos() to obtain valid screen coordinates.

• EEex_SetActorLocal(actorID, localName, value):

  Sets a LOCALS variable in the actor's .CRE as if a SetGlobal(<localName>, "LOCALS", <value>) script action was executed by the given actor.

• EEex_SetAreaGlobal(areaResref, globalName, value):

  Sets an <areaResref> variable in an .ARE as if a SetGlobal(<globalName>, <areaResref>, <value>) script action was executed.

• EEex_SetGlobal(globalName, value):

  Sets a "GLOBAL" variable in the .GAM as if a SetGlobal(<globalName>, "GLOBAL", <value>) script action was executed.

• EEex_UpdateActionbar():

  Forces the actionbar to refresh its state. Use if making changes with EEex_SetActionbarButton() outside of an actionbar listener.

• EEex_WithinCyclicRange(num, num2, range, lowerBound, higherBound):

  Returns true if num2 is within <range> positions of num in the cyclic bounds. See EEex_CyclicBound() for more info about cyclic ranges.

• EEex_WriteLString(address, toWrite, maxLength):

  Function for editing text fields without a terminating NULL (e.g. resrefs).

  Like the WeiDU WRITE_ASCII function:
  EEex_WriteLString(0x20, "SPWI304", 8) equals WRITE_ASCII 0x20 ~SPWI304~ #8