Func - Object Information

Sections in this file:

Campaign Data
User Input
Misc
Access Other Creatures

The func object is a resource with many different general-purpose functions designed to make scripting easier.
Functions are accessed with the syntax "func.FunctionName". func is accessible from all the scripts in DM Genie.

Campaign Data

Go back to top

Use these functions to access campaign data. Some of these functions return objects such as
Skill, Spell, Race, etc.

Members

Functions

Function GetNumberOf_Skills() As Integer

Function GetNumberOf_Spells() As Integer

Function GetNumberOf_Feats() As Integer

Function GetNumberOf_Conditions() As Integer

'Note: Each of these functions returns the number of X in the campaign. Note that some of the intervening items might not be valid (deleted spells, etc.). So even if func.GetNumberOf_Skills returns 200, skill number 145 might have been deleted and so not be valid.

'Skills

'#Campaign Data
Function GetSkillNum(SkillName As String) As Integer

'Returns the Skill ID from the skill name. Will be -1 if the skill isn't found.

Function GetSkillName(SkillNum)

'Returns the skill name from the skill ID (or number).

Function GetSkillObj(SkillNum As Integer)

'Returns the skill object corresponding to the SkillNum indicated.
'Check for validity with func.ValidSk

Function GetSkillAbility(SkillNum)

'Returns the skill relevant ability name for the given skill ID (or number)

Function GetSkillArmorCheck(SkillNum)

'Returns true or false depending on whether the skill has an armor check penalty

Function GetSkillTrainedOnly(SkillNum)

'Returns true or false depending on whether the skill can only be used by trained PCs (1 or more ranks)

'Spells

Function GetSpellNum(SpellName As String, Optional PsionicMode As Boolean = False) As Integer

'Returns the Spell ID from the spell name. Returns 0 if not found.
'"Cure Light Wounds, Mass" will match "Mass Cure Light Wounds". Also, "Tasha's Hideous Laughter" will match both "Hideous Laughter" and "Ta's Hideous Laughter".

Function GetSpellName(SpellNum)

'Returns the Spell name from the Spell ID (or number)

Function GetSpellObj(SpellNum As Integer)

'Returns a spell object from the spell number (see Scripting - Spell Object). This allows you to view and edit every spell property.
'Spells and psionic powers have the same data format in DM Genie - so you can use this same function to edit a psionic power.

Function GetSpellLevel(SpellNum, ClassName)

'Scan the description to find the spell level matching ClassName
' Will returnt -1 if nothing is found

Function SpellIsFromSchool(SpellNum As Variant, SchoolName As Variant) As Boolean

'Returns True is the Spell # SpellNum is from the school SchoolName.
'(This works by checking if SchoolName is in the description before the Level: string)

Function SpellIsOfType(SpellNum As Variant, SpellType As Variant) As Boolean

'Returns True is the Spell # SpellNum is SpellType.
' (This works by checking if SpellType is in the description before the Level: string)

Function GetPPCost(PowerName As String) As Integer

'Returns the Power Point cost of the given power

'Conditions

Function GetConditionNum(CondName As String) As Integer

'Return the condition number from its name

'Feats

Function GetFeatName(FeatNum)

'Returns the feat name from the feat ID (or number)

Function GetFeatNum(FeatName)

'Returns the feat ID from the feat name

Function GetFeatParam(FeatNum As Integer, ParamName As String)

'Returns a parameter (ParamName) from the feat of ID FeatNum

Function SetFeatParam(FeatNum, ParamName As String, NewValue As Variant)

'Sets the feat parameter ParamName to NewValue for the feat FeatNum

'Race

Function GetRaceNum(RaceName As String) As Integer

'Returns the race number (ID) from the name of the race

Function GetRace(RaceNum As Integer) As Race

'Returns the race object from the # of the race

Function GetRaceFromName(RaceName As String) As Race

'Returns the race object from the name of the race

'Items
Function FindStdItem(ItemName As String) As ItemObj

'This function looks for an item in the standard items list, matching the name "ItemName"
'It returns a copy of the item object found.
'Returns nothing (an empty object) if the name did not match.
'
'Usage Example:
' MyObj = func.FindStdItem("Backpack")
' if not MyObj is Nothing then Cr.AddItemObj(MyObj)
'

User Input

Go back to top

Members

Functions

Function InputInteger(Question As String, Optional min_value As Long = 0, Optional max_value As Long = 2000000) As Long

'Asks for user input as per input box, but validates result to ensure it is an integer (long) value. If not, it asks for input again. Also validates "min" and "max" (useful for dice input ranges).

Function InputBoxLong(Prompt As String, Optional Title As String = "Input Text", Optional default As String = "", Optional MultiLine As Boolean = False) As String

'Replacement of a standard input box where a large, (optionally) multiline text box is displayed instead. Can be used to display or prompt for long lists.

Function Choose(Question As String, ParamArray Elements()) As Long

'Asks the user a question and displays a list of choices. After Question, enter each item followed by a comma and a numerical value corresponding to it. Returns -1 when the user presses cancel. For example:
'MyColorNum = func.Choose("Which is you favorite color?", "Blue", 1, "Red", 2, "Green", 3)

Function ChooseString(Question As String, ParamArray Elements()) As String

'Asks the user a question and displays a list of choices. After Question, enter each item string. Returns the string For example:
'MyColorName = func.ChooseString("Which is you favorite color?", "Blue", "Red", "Green")

Function ChooseDomain(Question As String) As String

'Asks the user to select one domain from the list of domains specified in RULES.TXT

Function ChooseSkill(Question As String) As Long

'Asks the user a question and displays a list of all skills. The function returns the skill number of the skill the user selected (-1 if cancelled).

Function ChooseSpell(FeatName As String, Optional OnlyKnownSpells As Boolean = False) As String

'Ask the user to choose a spell or a power for which he will apply FeatName. Returns the name of the spell or power.
'Set OnlyKnownSpells to true (optional) to limit the display to only spells known by the PC

Function ChoosePower(FeatName As String, Optional OnlyKnownSpells As Boolean = False) As String

'Ask the user to choose a spell or a power for which he will apply FeatName. Returns the name of the spell or power.
'Set OnlyKnownSpells to true (optional) to limit the display to only spells known by the PC

Function ChooseWeapon(FeatName As String) As String

'Returns a string chosen by the user (presumably the name of a weapon, but there is a box which can hold anything).

Function ChooseWeaponOnly(Message As String) As String

'Input box that asks the user to choose a weapon from the standard list. No custom choice is allowed.

Function ChooseRace(Title As String, FilterType As Boolean, DefaultType As String, FilterPC As Boolean) As Integer

'- Opens the Choose Race dialog.
'Title: Dialog caption
'FilterType: Set true to filter by type
'DefaultType: The type to filter
'FilterPC: Set true to filter only PC races
'Returns the race ID#

Function ChooseCreature(Question As String, GroupNum As Variant, ShowEnemies As Variant, ShowFriends As Variant) As Creature

'Presents the user with a list of creatures
' - GroupNum: 0 = currently selected group
' 1 = PC's Party
' 2 = Current Encounter
' (under Player Genie there is only one group - all of these choices will use it)
' - ShowEnemies, ShowFriends: Set to True to show either or both of these.
'Returns: The selected creature object, or Nothing if user cancelled the choice

Sub OpenLevelingWizard(TheCreature As Creature, ClassName As String, Levels As Integer, CreatureAdvance As Boolean)

'Opens the leveling wizard with those default settings.

Misc

Go back to top

Members

Functions

Sub AddToCombatLog(Message As Variant)

'Adds a line to the combat log. Can use rich text tags. Do not add a "\par" code at the end. For a list of RTF codes, see Formatting Rich Text Strings.

Function CVInt(invar) As Integer

'Converts an input string or number to a valid integer

Function CVSng(invar) As Single

'Converts an input string or number to a valid single

Function CheckName(ListOfNames, ThisName) As Boolean

'ListOfNames = semicolon-separated list of names.
'Returns true if ThisName is in ListOfNames

Function MakeRollString(Total, roll, ParamArray Bonuses() As Variant)

'Makes a string for the combat log like "14 (Roll 3, +2 bonustype, -3 bonustype)"
'MakeAttackString(14,3, +2, "bonustype", -3, "bonustype")

Function CopyAttack(vSourceAt As Variant, vDestAt As Variant)

'Copies the attack SourceAt into DestAt

Function MakeNewAttack() As Variant

'Makes a new attack object, returns it

Function RollDice(DiceStr) As Long

'Rolls the dice string indicated and returns the value.

Function RollMaximize(DiceStr As String, Maximized As Boolean) As Long

'Returns the maximum value a dice string could be rolled, if you set Maximized to true

Function ValidCr(CrCheck) As Boolean

'Returns true if the variable is a valid reference to a Creature

Function ValidGr(GrCheck) As Boolean

'Returns true if the variable is a valid reference to a group

Function ValidAt(AtCheck) As Boolean

'Returns true if the variable is a valid reference to an attack

Function ValidSk(Check) As Boolean

'Returns true if the variable is a valid reference to a skill

Function ValidCond(Check) As Boolean

'Returns true if the variable is a valid reference to a condition

Function ValidRa(inrace) As Boolean

'Returns true if the variable is a valid reference to a race

Function ValidSp(VarSp) As Boolean

'Returns true if the variable is a valid reference to a spell

Function GetSizeValue(SizeStr As String)

'Returns an integer value based on the first letter of a size string.
'M: 0; L: +1; S: -1; and so on. Returns 0 if sizestr is not a valid size abbrev

Function GetLastDamage()

'Returns the LastDamage object, which is the Damage object containing the last attack roll

Sub SetAutoDamage(Damage As Integer, Optional Kind As Integer = 0, Optional Touch As Boolean = False, Optional AC, Optional CritAC As Integer = -999, Optional CritDamage As Integer = 0, Optional Subdual As Boolean = False, Optional DamageType As String)

'This allows a script to save damage for use with the 'AutoDamage' menu.
'Kind = 0 for melee, 1 for ranged. CritAC is the critical threat AC hit; CritDamage is the extra damage from a critical.
'Everything except Damage is optional and will default to a melee touch attack that hits AC 999 (thus always hits) with no critical. E.g. func.SetAutoDamage 12 will always cause 12 hp of damage.

Function Append(ByVal StringToChange As String, AdditionalString As String) As String

'This function will take StringToChange and add AdditionalString after it, with a comma if necessary.
'The return value is the appended string. Use like this:
'cr.FeatMisc = func.Append(cr.FeatMisc, "Weapon Specialization")

Function Remove(ByVal StringToChange As String, StringToRemove As String) As String

'Takes StringToChange, searches for StringToRemove, and removes it. If there is a trailing
' comma or period, it is removed also.

Function GetLineNum(ins, LineNum)

'Returns line #x from the input string ins, a long string separated by carriage returns and line feeds
'LineNum starts at 0

Function Capital(ins)

'Capitalizes the first letter of each word in the input string ins

Function GetTimeStat(Name As String, Optional Number As Integer)

'This function returns a particular value of the current time
' The Name argument is a non-case-sensitive string describing the type of value.
' The Number argument is required only when requesting moon phase.
'
'Here follows a list of accepted parameter names
' Current time:
' hour, minute, second: Returns the corresponding integer
' PM: True if PM, false if AM
' Current date:
' day, month, year: Returns the corresponding integer
' monthstr: Month as a string
' monthabbrev: month as a string, abbreviated
' dow: day of the week, as a full string
' dowabbrev: day of the week, abbreviated
' Absolute time/date:
' curtime: Current time as the number of seconds since midnight today. An integer.
' curdate: Current date, in days since year 0. An integer.
' curdatetime: The number of days since year 0, with fractional days being counted as well. A double.
' Moons
' moonphase: Phase of the moon number Number, at current date/time, From 0 to 100% full.
' moonphaseincreasing: Returns a boolean, true if the phase in an increasing stage. True means a waxing moon, False means a waning moon.
' Sun
' sun: A string, either Night/Day/Twilight/Sunrise/SunsetSun
' Weather
' Clouds: Description of cloud cover, string"
' temperature: Temperature in Celsius (single). Farenheight = 32 + celsius * 1.8
' wind: Windspeed, single
' precipitation: Precipitation description, string
' weatherdesc: The overall weather description, string

Access Other Creatures

Go back to top

These functions return a Creature object that you can modify exactly like the Cr object. For example, a feat could set a condition for members of the PC's Party.

Members

Functions

Sub GetNextCreatureInit(GroupNum As Variant)

'Initializes the group to be looped in GetNextCreature
' - GroupNum: 0 = currently selected group
' 1 = PC's Party
' 2 = Current Encounter
' (under Player Genie there is only one group - all of these choices will use it)

Function GetNextCreature() As Creature

'Returns, as an object, the next creature in the group selected by GetNextCreatureInit
'Will return Nothing when it runs out of creatures.
'Creatures are returned in alphabetical order. All are returned, enemies or not.
'--- Example use: ---
'dim MyCreature
'func.GetNextCreatureInit 0
'Set MyCreature = func.GetNextCreature
'While (Not MyCreature Is Nothing)
' MyCreature.HP = MyCreature.HP - 5
' Set MyCreature = func.GetNextCreature
'Wend

Function GetCreatureName(TheName As Variant) As Creature

'Returns, as an object, the first creature whose name matches TheName
' The search is case insensitive
' This looks only in the currently selected group
' Returns Nothing if no match is found.
' If multiple creatures share the same name only the first is returned.

Documentation for DM Genie and Player Genie, page Func. Copyright © Mad Scientist Studios, 2006.
Help Contents | DM Genie home page
Click here if you cannot see the table of contents on the left