Author Topic: Some documentation  (Read 976 times)

Offline Wisp

  • Moderator
  • Planewalker
  • *****
  • Posts: 1176
Some documentation
« on: May 17, 2010, 05:06:12 PM »
Code: [Select]
or & \DEFINE{GET!FILE!ARRAY} \ttref{String} path \ttref{regexp} &
  The array \verb+$string(0)+, \verb+$string{1}+ etc is set to the file names, including path, that match regexp in path. The path is relative to the installation directory (e.g. save/000000000-Auto-Save).\\
or & \DEFINE{GET!DIRECTORY!ARRAY} \ttref{String} path \ttref{regexp} &
  Like \ttref{GET!FILE!ARRAY} except regexp is matched against directories instead of files.\\
or & \DEFINE{ACTION!DEFINE!ASSOCIATIVE!ARRAY} \t{\ttref{String} BEGIN key1 => result1} \Slist \t{END} &
  Sets the array \verb+$string+, indexed by the keys, to the corresponding results. The results can either be \ttref{String}s or \ttref{value}s.
  Example:
  \begin{verbatim}
ACTION_DEFINE_ASSOCIATIVE_ARRAY mix_with_blue BEGIN
  red => purple
  yellow => green
END
  \end{verbatim}\\

Code: [Select]
or & \DEFINE{GET!OFFSET!ARRAY} \ttref{String} \t{seven \ttref{value}s} &
  The seven values are:
\begin{verbatim}
1. Offset
2. Read length of "Offset"
3. Iterations
4. Read length of "Iterations"
5. Index
6. Read length of "Index"
7. Length between iterations.
\end{verbatim}

WeiDU comes with a number of pre-defined sets of values for GET!OFFSET!ARRAY. These sets are:
\begin{verbatim}
ITM_V10_HEADERS (0x64 4 0x68 2 0 0 0x38)
ITM_V10_GEN_EFFECTS (0x6a 4 0x70 2 0x6e 2 0x30)
WMP_AREAS (0x34 4 0x30 4 0 0 0xf0)
WMP_LINKS (0x38 4 0x3c 4 0 0 0xd8)
\end{verbatim}

GET!OFFSET!ARRAY performs "Iterations" number of reads and sets the array \verb+$string(0)+, \verb+$string(1)+ etc to the result of these reads. A more detailed explanation can be had in the \ttref{GET!OFFSET!ARRAY and GET!OFFSET!ARRAY2} tutorial.\\

or & \DEFINE{GET!OFFSET!ARRAY2} \ttref{String} \t{eight \ttref{value}s} &
  The eight values are:
\begin{verbatim}
1. Offset2
2. Offset
3. Read length of "Offset"
4. Iterations
5. Read length of "Iterations"
6. Index
7. Read length of "Index"
8. Length between iterations
\end{verbatim}

WeiDU comes with a pre-defined set of values for GET!OFFSET!ARRAY2. This set is:
\begin{verbatim}
ITM_V10_HEAD_EFFECTS (0x6a 4 0x1e 2 0x20 2 0x30)
\end{verbatim}
As you can see, the value for Offset2 isn't included in the set, since it varies.

"Offset2" corresponds to the result from \ttref{GET!OFFSET!ARRAY}. "Offset" is read from the start of the file. "Iterations" and "Index" are read from Offset2 + value. Apart from that GET!OFFSET!ARRAY2 functions like \ttref{GET!OFFSET!ARRAY}. A more detailed explanation can be had in the \ttref{GET!OFFSET!ARRAY and GET!OFFSET!ARRAY2} tutorial.\\
     
or & \DEFINE{DEFINE!ASSOCIATIVE!ARRAY} \t{\ttref{String} BEGIN key1 => result1} \Slist \t{END} &
  Sets the array \verb+$string+, indexed by the keys, to the corresponding results. The results can either be \ttref{String}s or \ttref{value}s.
  Example:
  \begin{verbatim}
DEFINE_ASSOCIATIVE_ARRAY mix_with_blue BEGIN
  red => purple
  yellow => green
END
  \end{verbatim}\\

Code: [Select]
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{\DEFINE{GET!OFFSET!ARRAY and GET!OFFSET!ARRAY2}}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

GET!OFFSET!ARRAY and GET!OFFSET!ARRAY2 are means for obtaining information about certain types of file structures without using the usual READs, FORs etc. GET!OFFSET!ARRAY can, for example, be used to find the starting offsets for all the extended headers (abilities) in an item, while GET!OFFSET!ARRAY2 can be used to find the starting offsets for all extended effects in the item. Since the effect structure is organised by the ability structure, GET!OFFSET!ARRAY2 is conventionally used together with GET!OFFSET!ARRAY.

The seven values required by GET!OFFSET!ARRAY are:
\begin{verbatim}
1. Offset
2. Read length of "Offset"
3. Iterations
4. Read length of "Iterations"
5. Index
6. Read length of "Index"
7. Length between iterations.
\end{verbatim}

Acceptable values for read length are 0 (don't read), 2 (SHORT) and 4 (LONG). Length between iterations depends on the file structure you are working with. In our item example, length between iterations is 0x38 while we are using GET!OFFSET!ARRAY. If we were working with a spell instead, it would be 0x28.

In the item example, "Offset" is 0x64, which gives the ability offset when read.
The value read from "Iterations" is the number reads that should be performed. "Iterations" is 0x68 in the item example, which gives the number of abilities when read.
The value read from "Index" is the number of iterations into the file the current read should be made. This is not always relevant for GET!OFFSET!ARRAY, but for reading general effects (on-equip effects), this is 0x6e.

GET!OFFSET!ARRAY2 requires an additional value. Let's call it Offset2. This value is normally obtained as the result from GET!OFFSET!ARRAY. In our item example this value is the starting offset for the current ability. The value of "Offset" is now 0x6a, which gives the effect offset. The value of "Iterations" is now 0x1e, which gives the number of effects, the value of "Index" is now 0x20 and both are read from Offset2 + value (unlike GET!OFFSET!ARRAY where they are read from the start of the file).

For example, if we wanted to know how many levels Blackrazor can drain, we could use this code:
\begin{verbatim}
COPY_EXISTING miscbc.itm override
  GET_OFFSET_ARRAY ab_array 0x64 4 0x68 2 0 0 0x38
  PHP_EACH ab_array AS int => ab_off BEGIN
    CLEAR_ARRAY fx_array
    GET_OFFSET_ARRAY2 fx_array ab_off ITM_V10_HEAD_EFFECTS
    PHP_EACH fx_array AS int => fx_off BEGIN
      READ_SHORT fx_off fx_type
      PATCH_IF fx_type = 216 BEGIN
        READ_LONG fx_off + 0x4 amount
        PATCH_PRINT "I drain %amount% level(s)"
      END
    END
  END
BUT_ONLY
\end{verbatim}

You need to use CLEAR!ARRAY before invoking GET!OFFSET!ARRAY2, or you can run into problems with PHP!EACH using old values. It may also be prudent to clear the array created by GET!OFFSET!ARRAY, in case you use GET!OFFSET!ARRAY more than once.

Maybe it's even correct, useful and not confusing.

Offline the bigg

  • The Avatar of Fighter / Thieves
  • Moderator
  • Planewalker
  • *****
  • Posts: 3804
  • Gender: Male
Re: Some documentation
« Reply #1 on: May 17, 2010, 05:10:49 PM »
Thank you very much (both for writing this up and for writing in latex)  :)
Author or Co-Author: WeiDU (http://j.mp/bLtjOn) - Widescreen (http://j.mp/aKAiqG) - Generalized Biffing (http://j.mp/aVgw3U) - Refinements (http://j.mp/bLHoCc) - TB#Tweaks (http://j.mp/ba02Eg) - IWD2Tweaks (http://j.mp/98OFYY) - TB#Characters (http://j.mp/ak8J55) - Traify Tool (http://j.mp/g1Ry9A) - Some mods that I won't mention in public
Maintainer: Semi-Multi Clerics (http://j.mp/9UeIwB) - Nalia Mod (http://j.mp/dng9l0) - Nvidia Fix (http://j.mp/aRWjjg)
Code dumps: Detect custom secondary types (http://j.mp/hVzzXG) - Stutter Investigator (http://j.mp/gdtBn8)

If possible, send diffs, translations and other contributions using Git (http://j.mp/aBZFrq).

 

With Quick-Reply you can write a post when viewing a topic without loading a new page. You can still use bulletin board code and smileys as you would in a normal post.

Warning: this topic has not been posted in for at least 120 days.
Unless you're sure you want to reply, please consider starting a new topic.

Name: Email:
Verification:
Type the letters shown in the picture
Listen to the letters / Request another image
Type the letters shown in the picture:
What color is grass?:
What is the seventh word in this sentence?:
What is five minus two (use the full word)?: