List of WEIDU functions

[DavidW]

In the last few years there's been a transformative improvement in the function library shipped with WEIDU, but the list of functions is hard to navigate. I've just spent a few minutes organizing it for my own benefit, and thought I'd share.

Morphic functions (work as ACTION or SPELL, don't alter game resources)

No-side-effect, no game dependency

tb#factorial
tb#fix_file_size
SUBSTRING
DIRECTORY_OF_FILESPEC
FILE_OF_FILESPEC
RES_OF_FILESPEC
EXT_OF_FILESPEC

No side-effect, game-dependent

RES_NUM_OF_SPELL_NAME
RES_NAME_OF_SPELL_NUM
NAME_NUM_OF_SPELL_RES

Patch functions (work on specific file types)

.ARE

ADD_AREA_ITEM
ADD_AREA_REGION_TRIGGER
ALTER_AREA_ACTOR
ALTER_AREA_CONTAINER
ALTER_AREA_DOOR
ALTER_AREA_ENTRANCE
ALTER_AREA_REGION
DELETE_AREA_ITEM
REPLACE_AREA_ITEM

.CRE

ADD_CRE_EFFECT
ADD_CRE_ITEM_FLAGS
ADD_CRE_SCRIPT
ALTER_EFFECT
CLONE_EFFECT
DELETE_CRE_ITEM
DELETE_EFFECT
FJ_CRE_VALIDITY
FJ_CRE_REINDEX
FJ_CRE_EFF_V2
READ_SOUNDSET
REMOVE_CRE_ITEM_FLAGS
SET_CRE_ITEM_FLAGS
T-CRE_EFF_V1
WRITE_SOUNDSET

.ITM

ADD_ITEM_EFFECT
ADD_ITEM_EQEFFECT
ALTER_EFFECT
ALTER_ITEM_HEADER
CLONE_EFFECT
DELETE_EFFECT
DELETE_ITEM_HEADER
ITEM_EFFECT_TO_SPELL

.SPL

ADD_SPELL_EFFECT
ADD_SPELL_CFEFFECT
ALTER_EFFECT
ALTER_SPELL_HEADER
CLONE_EFFECT
DELETE_EFFECT
DELETE_SPELL_HEADER

.STO

DELETE_STORE_ITEM
REPLACE_STORE_ITEM

.WMP

ADD_WORLDMAP_LINKS
DELETE_WORLDMAP_LINKS

Action functions

FIND_FREE_PRVZ_INDEX
GET_UNIQUE_FILE_NAME
HANDLE_AUDIO
HANDLE_CHARSETS
HANDLE_TILESETS
HANDLE_CHARSETS
INSTALL_PRVZ

Obsolete PATCH functions 

DELETE_CRE_EFFECT (use DELETE_EFFECT)
ALTER_ITEM_EFFECT (use ALTER_EFFECT)
ALTER_SPELL_EFFECT (use ALTER_EFFECT)
DELETE_ITEM_EFFECT (use DELETE_EFFECT)
DELETE_ITEM_EQEFFECT (use DELETE_EFFECT)
DELETE_SPELL_EFFECT (use DELETE_EFFECT)

 

[DavidW]

Incidentally, the absence of anything like this five or six years ago was what drove me to write SFO, SCS's own function library. That library is still rather more powerful than WEIDU's native library, but it's slower, has a steeper learning curve (especially if you haven't done any functional programming) and is awkward to include piecemeal in other mods - which is why I'm trying to get my head around WEIDU's library.

[Luke]

I'd like to add the following (patch) functions about .STO files (WeiDU v245 or later required!):

• ADD_STORE_ITEM_EX: Adds an item to the store.
• ADD_STORE_DRINK: Adds a drink to the store.
• ADD_STORE_CURE: Adds a cure to the store.
• ADD_STORE_PURCHASE: Adds an item category to the store.
• REMOVE_STORE_ITEM_EX: Removes an item from the store.
• REMOVE_STORE_DRINK: Removes a drink from the store.
• REMOVE_STORE_CURE: Removes a cure from the store.
• REMOVE_STORE_PURCHASE: Removes an item category from the store.

Edited February 16, 2019 by Luke

[DavidW]

1 hour ago, Luke said:

I'd like to add a couple of functions about .STO:

• REMOVE_STORE_ITEM
• REMOVE_STORE_PURCHASE (requires WeiDU v245 or later, documentation is still pending...)

REMOVE_STORE_ITEM isn't a function, it's a base-level WEIDU command. REMOVE_STORE_PURCHASE does seem to be a function, but I'm only listing documented functions.

[Luke]

12 hours ago, DavidW said:

REMOVE_STORE_ITEM isn't a function, it's a base-level WEIDU command.

Yep, you're right, I'll remove it.....

As far as REMOVE_STORE_PURCHASE is concerned, I managed to find the interim documentation. As you can see, @argent77 defined several functions for adding or removing STO structures....

[DavidW]

Cool. But I'll wait to add them until they're in the official documentation. (Your own comment, immediately below, is clear enough in the meantime.)

[Luke]

On 2/15/2019 at 5:30 PM, DavidW said:

That library is still rather more powerful than WEIDU's native library,...

Indeed! So, do you recommend it in the end?

I must admit I'm very interested into trying it out... I just need to slightly tweak "install_sfo.tpa" in order to adjust it to my needs, right?

[DavidW]

4 hours ago, Luke said:

Indeed! So, do you recommend it in the end?

I must admit I'm very interested into trying it out... I just need to slightly tweak "install_sfo.tpa" in order to adjust it to my needs, right?

I recommend it to *me*!

For anyone else, it depends on use case, programming experience, and willingness to dig through code. It’s significantly more powerful than pretty much any other tool out there - on the other hand, it’s very abstract, almost completely undocumented, can run quite slowly if you’re not careful, and I’m unlikely to provide more than minimal help with it. You have to refer to the code itself quite a lot to use it.

The intermediate choice is the ‘sfo_lite’ library which Ascension uses. That’s also undocumented (though it’s somewhat more likely to get documented in the medium term) but it’s conceptually simpler and Ascension’s code itself gives lots of examples.

[Luke]

58 minutes ago, DavidW said:

...almost completely undocumented...

Yeah, this is the main issue... Anyway, the existing documentation is *probably* enough to get started and I'd like to try...

In case I need to report bugs and the like, should I do that via PMs or by starting a new thread in SCS subforum?

[DavidW]

1 hour ago, Luke said:

the existing documentation is *probably* enough to get started and I'd like to try...

You mean the fragments of documentation in the mod folder itself, or the G3 thread on 'functional WEIDU'? (I'm guessing the latter, but I should say that they're a very partial effort, before I realised the amount of work was way more than I was willing to do for the very small number of people it would benefit.)

The main thing that the mod folder documentation doesn't mention is that the 'instruction=>value' pairs in SFO's inputs are actually function-argument pairs. 'instruction' is a patch function that takes 'argument' as a STR_VAR (and also some other arguments to facilitate looping through extended offsets); 'value' actually gets plugged into the 'arguments' slot. About three quarters of those patch functions are built automatically, and do simple things like writing to specified offsets; the others are handwritten. The 'functional WEIDU' thread talks a bit about that.

What the functional WEIDU thread doesn't tell you is that there is considerable preprocessing done on the argument part of the function-argument pair before it gets slotted in. In patching effects, for instance, the following are legal:

duration=>"if duration>0 then duration*2 else 0"
resource=>"resource in [spwi205->spwi205a sppr304->sppr304a default->no_change]"

With the benefit of seven years' hindsight, it's unclear if that was a good idea - it is in principle very powerful, and drastically simplifies writing some bits of code, but the slowdown is significant and I don't use it *that* much. The underlying code for the preprocessing is in lib_evaluate.

In general I would be wary about using SFO to do large-scale patching if you can help it, on speed grounds. It's best suited for complex editing of individual resources (it's great for populating areas in quests, for instance, or doing surgery on specific spells). But applying relatively simple patches to large numbers of spells, say, is much much faster using WEIDU's built-in ALTER_EFFECT family of functions (or my extension of them) than using SFO. And I'd strongly advise against using SFO's 'edit_all_<object>' functionality - if you're looping through every object in the game there will be way faster ways to do it. If necessary, do a hardcoded loop through everything to obtain a resource list, then apply SFO code to that list. (There are lots of examples of this in SCS.) 

1 hour ago, Luke said:

In case I need to report bugs and the like, should I do that via PMs or by starting a new thread in SCS subforum?

Start a thread. (If there are actual bugs, they're likely to entail SCS (or WoP) bugs.)

From the department of expectations management: I'm happy for you, or anyone, to borrow SFO and play with it, and even use it in released mods (with credit) but it's as-is - I don't support it in any way and I'm not at all guaranteeing help with any issue. (Much as with SSL.) I decided a long time ago that working SFO into a genuine community resource wasn't viable unless I was prepared to change my hobby activity from modding to tool-building.

[Luke]

On 6/25/2020 at 5:41 PM, DavidW said:

You mean the fragments of documentation in the mod folder itself, or the G3 thread on 'functional WEIDU'?

I started playing with SFO using the fragments of documentation in the mod folder itself.

On 6/25/2020 at 5:41 PM, DavidW said:

It's best suited for complex editing of individual resources...

And what about creating resources (e.g. STO / CRE / SPL / ITM / PRO files) from scratch? IMHO, that's great too...

I mean, the key point here is the functional way of doing things. As you said, that means shorter and more readable code; less buggy code; code that's much easier to adjust at a bulk level. I like it!

Yes, maybe it's not very suited for doing simple editing of individual resources, but still worth it...? IMHO, yes.

LAF edit_creature
STR_VAR
	creature = "bandit"
	editstring = "xp=>1200"
END

// Versus

COPY_EXISTING "bandit.cre" "override"
	WRITE_LONG 0x14 1200	// You can basically "forget" about 0x14 and related 'magic' numbers...
BUT_ONLY

 

[subtledoctor]

I don't know.  I can't say I know how SFO works, but I feel like I would probably need to have its documentation open in my browser, to make sure I'm using it right; and it is similarly likely I would have the IESDP page for the CRE file structure open when editing with normal Weidu commands.

11 hours ago, Luke said:

And what about creating resources (e.g. STO / CRE / SPL / ITM / PRO files) from scratch?

I use Weidu's CREATE command a bunch...

[DavidW]

I certainly have to look things up in SFO a lot. I think the main advantages in simple edits like the one Luke gives are that code is basically self-documenting and, more importantly, that errors tend to produce install-time failures rather than silent bugs. If you throw SFO this code:

LAF edit_creature 
	STR_VAR creature = "bandit"
			editstring = "xpv=>1400"
END

then the code will refuse to install (it'll throw a 'function CRE_xpv does not exist' error or similar). If you do this:

COPY_EXISTING "bandit.cre"
	WRITE_LONG 0x16 1400

then WEIDU will install fine and the code looks indistinguishable from the correct code on casual examination, but the file will be changed incorrectly.

To be fair, you can get a lot of that advantage through using NAME and the like in baseline WEIDU.

[Magus]

Functional way is obviously much better than just writing bytes left and right. The holy grail, however, would be object-oriented style. But I'm afraid it would take a tool other than WeiDU.

21 hours ago, DavidW said:

I think the main advantages in simple edits like the one Luke gives are that code is basically self-documenting and, more importantly, that errors tend to produce install-time failures rather than silent bugs.

These are both very important points, I agree. (And also I think that "sanity" checks included in many mods are actually detrimental to the overall mods quality in the long term. Install-time failures are immidiately obvious and get fixed relatively quick. But if mods "work around" issues by skipping the files, errors can linger for many years).

And even when not using SFO, basic self-documenting not that hard to achieve by simply defining the corresponding constants:

COPY_EXISTING ~plyspid.itm~  ~override~
  PHP_EACH web_spells AS index => spell BEGIN
    LPF ADD_ITEM_EQEFFECT
      INT_VAR
        opcode = OPCODE_protection_from_spell
        target = TARGET_EFF_self
        timing = TIMING_while_equipped
        resist_dispel = BYPASS_MR
      STR_VAR
        resource = EVAL ~%spell%~
    END
  END
BUT_ONLY

 

22 hours ago, subtledoctor said:

I feel like I would probably need to have its documentation open in my browser, to make sure I'm using it right; and it is similarly likely I would have the IESDP page for the CRE file structure open when editing with normal Weidu commands.

A properly structured documentation can be added to intellisense. Which doesn't obsolete the need to read the actual doc first, but still reduces the amount of alt-tabbing.

Edited July 16, 2020 by qwerty1234567