147 |
148 |
149 |
MXPF is an xEdit scripting library that provides a variety of functions
150 | for the generation of patches. Want to rebalance armor and weapons in
151 | Skyrim? Done. Apply a new particle effect to every weather? Easy.
152 | Change the configuration of all NPCs? Cake.
153 |
154 |
155 |
MXPF is comprised a suite of functions that do the work of finding the
156 | records you want to patch, identifying/creating a patch file, and
157 | copying records to the patch. Where you would normally have to learn
158 | to do all of these steps yourself, with MXPF you can accomplish
159 | everything you need with a few simple functions.
160 |
161 |
The project is available on GitHub and Nexus Mods. A test suite is
162 | available. There are also a bunch of example scripts available which show
163 | you how you can use MXPF and xEdit Scripting to solve problems.
164 |
165 |
You can report bugs and discuss features on the GitHub issues page.
166 | You can also talk with developers and other users on the xEdit HipChat,
167 | in the NexusMods comments section, and on r/xEdit.
168 |
169 |
Dependencies
170 |
189 |
190 |
Download and Setup
191 | You can download MXPF from
192 |
GitHub or
193 |
Nexus Mods.
194 | Once downloaded, you will need to copy the contents of the included
195 | Edit Scripts folder into xEdit's Edit Scripts folder. Once you've
196 | done that, you're set! You can then use MXPF in any script by
197 | putting
uses mxpf; after the unit declaration.
198 |
199 |
Running Tests
200 | You can run the MXPF tests through TES5Edit.
Note: You must have
201 | Skyrim installed to run the MXPF tests.
202 |
203 | - Install the TestMXPF ESP files into your data directory. If you're
204 | using a mod manager you could also, alternatively, install them as a new
205 | mod.
206 | - Load Skyrim.esm, TestMXPF-1.esp, TestMXPF-2.esp, and TestMXPF-3.esp
207 | into TES5Edit.
208 | - Wait for the background loader to complete.
209 | - Right-click any file in TES5Edit and choose Apply Script.
210 | - Select MXPF - Tests from the dropdown menu and click OK.
211 | - Wait for tests to complete. The log will be printed to TES5Edit's
212 | messages tab and will also be saved to Edit Scripts\jvTest\
213 |
214 |
215 |
User Constants
216 | User constants are constants that are meant to be set by the user.
217 | They will vary from machine to machine.
218 |
219 |
220 | boolean
221 |
222 | If set to true MXPF will generate debug messages throughout program
223 | execution. Use mxSaveDebug, mxPrintDebug or
224 | mxEchoDebug to control where debug information is sent.
225 |
226 |
227 |
228 | boolean
229 |
230 | If set to true MXPF will generate verbose debug messages. These are
231 | messages associated with every record processed by MXPF. Tracking
232 | these messages will slow down MXPF execution and may make debug logs
233 | extremely large.
234 |
235 |
236 |
237 | boolean
238 |
239 | If set to true and mxDebug is enabled, debug messages will be
240 | saved to a text document in mxpf/logs/mxpf-debug-{{time}}.txt.
241 |
242 |
243 |
244 | boolean
245 |
246 | If set to true, failure messages will be saved to a text document in
247 | mxpf/logs/mxpf-failures-{{time}}.txt.
248 |
249 |
250 |
251 | boolean
252 |
253 | If set to true and mxDebug is enabled, debug messages will be
254 | printed to xEdit's message log when FinalizeMXPF is called.
255 |
256 |
257 |
258 | boolean
259 |
260 | If set to true, failure messages will be printed to xEdit's message log
261 | when FinalizeMXPF is called.
262 |
263 |
264 |
265 | boolean
266 |
267 | If set to true and mxDebug is enabled, debug messages will be
268 | printed to xEdit's message log during execution. Echoing messages slows
269 | down script execution.
270 |
271 |
272 |
273 | boolean
274 |
275 | If set to true, failure messages will be printed to xEdit's message log
276 | during execution. Echoing messages slows down script execution.
277 |
278 |
279 |
280 |
Developer Constants
281 | Developer constants are constants that shouldn't be changed. These constants
282 | will be the same on every machine per version of MXPF, and can be useful
283 | in scripts that use MXPF.
284 |
285 |
286 | string
287 |
288 | This is a string representing the version of the MXPF file being used.
289 | You can check this to make sure that MXPF is of an adequate version for
290 | your script.
291 |
292 |
293 |
294 | string
295 |
296 | This is a string containing a comma-separated list of the filenames of
297 | all Bethesda master files associated with Skyrim.
298 |
299 |
300 |
301 | string
302 |
303 | This is a string containing a comma-separated list of the filenames of
304 | all hardcoded dat files that xEdit uses to emulate game executables.
305 | These files appears as Skyrim.exe, Fallout3.exe, Oblivion.exe, and
306 | FalloutNV.exe in xEdit.
307 |
308 |
309 |
310 |
Variables
311 |
312 |
313 | boolean
314 |
315 | Setting this to true will alter how LoadRecords behaves. When true,
316 | LoadRecords will only load records that are masters (i.e. new records
317 | in the file they're being processed in, not overrides). This allows you
318 | to avoid patching records that override records from files you've excluded
319 | or not included.
320 |
321 |
322 |
323 | boolean
324 |
325 | Setting this to true will alter how LoadRecords behaves. When true,
326 | LoadRecords will only load records that are override records (i.e.
327 | not new records). This is the opposite of mxLoadMasterRecords, and
328 | is useful if you want to only target override records in a few specific
329 | files. Note that using this option and mxLoadMasterRecords at
330 | the same time will result in no records being loaded.
331 |
332 |
333 |
334 | boolean
335 |
336 | Setting this to true will alter how LoadRecords behaves.
337 | When true, LoadRecords will load the winning overrides of records,
338 | which makes certain you don't overwrite the changes made to the record
339 | that would be present in game without the patch file you're generating.
340 | This is extremely important, and should almost always be set to true.
341 | This option can be used in conjunction with mxLoadMasterRecords
342 | or mxLoadOverrideRecords.
343 |
344 |
345 |
346 | boolean
347 |
348 | Setting this to true will have CopyRecordToPatch and
349 | CopyRecordsToPatch skip copying records that are already
350 | present in mxPatchFile. This is useful if you want to avoid
351 | performing duplicate work or patching the same value twice.
352 |
353 |
354 |
355 | IInterface
356 |
357 | Holds the patch file used by MXPF. This is useful to access if you
358 | need to change some attributes of the patch file created by your
359 | script.
360 |
361 |
362 |
363 |
General
364 |
365 |
366 | procedure InitializeMXPF;
367 |
368 | Initializes MXPF. You must call this at the beginning of every script
369 | before attempting to access any other MXPF function (except
370 | DefaultOptionsMXPF).
371 |
372 |
373 |
374 | procedure DefaultOptionsMXPF;
375 |
376 | Sets default options in MXPF. Usually you should call this whenever you
377 | use MXPF, as it sets the options that most use cases require. This method
378 | sets mxLoadMasterRecords, mxLoadWinningOverrides and
379 | mxSkipPatchedRecords to true.
380 |
381 |
382 |
383 | procedure FinalizeMXPF;
384 |
385 | Finalizes MXPF. You must call this at the end of every script you've
386 | used MXPF in. Calling this function frees all memory used by MXPF,
387 | cleans the masters of mxPatchFile if it is assigned, and
388 | prints/saves debug and failure messages, depending on user constants.
389 |
390 |
unit userscript;
391 |
392 | uses mxpf;
393 |
394 | function Initialize: integer;
395 | begin
396 | InitializeMXPF;
397 | DefaultOptionsMXPF;
398 | { Everything you want to do with MXPF goes here. }
399 | FinalizeMXPF;
400 | end;
401 |
402 |
Patch File Selection
403 |
404 |
405 | procedure PatchFileByAuthor(author: string);
406 |
407 | Selects the MXPF patch file by an author. If no file is
408 | found in the user's load order matching the specified author, the method
409 | will prompt the user to create one, and set the new file's author to the
410 | specified author string.
411 |
412 | Once selected, the patch file is stored in the mxPatchFile variable,
413 | and is used by MXPF Record Patching methods. Using author based file
414 | selection is preferable over filename selection because xEdit does not
415 | currently support a means of creating a file with a specified name (the
416 | user has to enter the name manually). Author selection also allows the
417 | user to have multiple instances of the patch file in their load order
418 | without having to manually rename them to avoid conflicts.
419 |
420 | NOTE: If there are multiple files with authors matching the specified
421 | author, this method will select the one closest to the top of the user's
422 | load order.
423 |
424 |
PatchFileByAuthor('MXPF ARMO Example');
425 |
426 |
427 |
428 | procedure PatchFileByName(filename: string);
429 |
430 | Selects the MXPF patch file by a filename. If no file is found
431 | in the user's load order matching the specified filename, the method will
432 | prompt the user to create one. If the created file does not match the
433 | desired filename, the script will inform the user that it will not
434 | recognize that file as the patch file in the future.
435 | Once selected, the patch file is stored in the mxPatchFile variable,
436 | and is used by MXPF Record Patching methods. Using filename based file
437 | selection is fairly standard, but selecting by author is better because
438 | it is more flexible.
439 |
440 |
PatchFileByName('MXPF ARMO Example.esp');
441 |
442 |
443 |
File Selection
444 |
445 |
446 | procedure SetExclusions(s: string);
447 |
448 | Sets the file selection mode to exclusion and loads the comma-separated
449 | list of files, s, into the mxFiles stringlist. Affects which
450 | files LoadRecords will load records from.
451 |
452 |
PatchFileByAuthor('MXPF ARMO Example');
453 | SetExclusions(mxHardcodedDatFiles);
454 | // now we won't load records from any of the hardcoded dat files
455 | LoadRecords('ARMO');
456 |
457 |
458 |
459 | procedure SetInclusions(s: string);
460 |
461 | Sets the file selection mode to inclusion and loads the comma-separated
462 | list of files, s, into the mxFiles stringlist. Affects which
463 | files LoadRecords will load records from.
464 |
465 |
PatchFileByAuthor('MXPF ARMO Example');
466 | SetInclusions('Skyrim.esm');
467 | // now we will only load records from Skyrim.esm
468 | LoadRecords('ARMO');
469 |
470 |
471 |
Record Processing
472 |
473 |
474 | procedure LoadRecords(sig: string);
475 |
476 | Loads records from the file selection specified with SetInclusions or
477 | SetExclusions. All records matching the input signature, sig
478 | will be added to the mxRecords list. Note: Calling this function
479 | does not clear the mxRecords list.
480 |
481 |
SetExclusions(mxHardcodedDatFiles);
482 | LoadRecords('WOOP'); // loads all WOOP (word of power) records
483 | LoadRecords('OTFT'); // loads all OTFT (outfit) records
484 |
485 |
486 |
487 | procedure LoadChildRecords(groupSig, sig: string);
488 |
489 | Loads records from the file selection specified with SetInclusions
490 | or SetExclusions. The group matching the input signature,
491 | groupSig will be searched for records matching the input signature
492 | sig. Found records will be added to the mxRecords list. You
493 | must use this function instead of LoadRecords when loading records
494 | from child groups. These are Dialogue Topic Info records (INFO) and any
495 | records that are children of Cell or Worldspace records (NAVM, ACHR, REFR, etc.).
496 |
497 |
SetExclusions(mxHardcodedDatFiles);
498 | // load all NAVM (navmesh) records from the WRLD (worldspace) group
499 | LoadChildRecords('WRLD', 'NAVM');
500 | // load all REFR (object reference) records from the CELL (cell) group
501 | LoadChildRecords('CELL', 'REFR');
502 |
503 |
504 |
505 | function GetRecord(i: integer): IInterface;
506 |
507 | Accesses records that were loaded through the LoadRecords function.
508 | Takes an index, i, to determine which record to load. You should
509 | use this function in conjunction with MaxRecordIndex.
510 |
511 |
LoadRecords('STAT');
512 | for i := 0 to MaxRecordIndex do begin
513 | rec := GetRecord(i);
514 | AddMessage('Found '+Name(rec));
515 | end;
516 |
517 |
518 |
519 | procedure RemoveRecord(i: integer);
520 |
521 | Removes the record at the specified index from the mxRecords
522 | list. Use this to apply additional filtering to records you want to
523 | patch after calling LoadRecords and before calling
524 | CopyRecordsToPatch. NOTE: You should always loop from the
525 | maximum index downto 0 when removing elements from the set
526 | you're looping through.
527 |
528 |
LoadRecords('WEAP');
529 | for i := MaxRecordIndex downto 0 do begin
530 | rec := GetRecord(i);
531 | damage := StrToInt(GetElementEditValues(rec, 'DATA\Damage'));
532 | // remove the weapon if its damage is less than 20
533 | if damage < 20 then
534 | RemoveRecord(i);
535 | end;
536 |
537 |
538 |
539 | function MaxRecordIndex: integer;
540 |
541 | Gets the number of items in mxRecords minus 1, the maximum
542 | index you can call GetRecord with successfully. This is for
543 | use when looping through loaded records.
544 |
545 |
546 |
Record Patching
547 |
548 |
549 | function CopyRecordToPatch(i: integer): IInterface;
550 |
551 | Copies the record at index i in mxRecords to the
552 | mxPatchFile. Adds required masters to mxPatchFile
553 | if they haven't been added yet. This provides more control than
554 | CopyRecordsToPatch.
555 |
556 |
LoadRecords('NPC_');
557 | for i := 0 to MaxRecordIndex do begin
558 | rec := GetRecord(i);
559 | // instead of using RemoveRecord, we can just copy specific
560 | // records with CopyRecordToPatch
561 | if GetElementEditValues(rec, 'ACBS\Flags\Female') = '1' then
562 | CopyRecordToPatch(i);
563 | end;
564 |
565 |
566 |
567 | procedure CopyRecordsToPatch;
568 |
569 | Copies all loaded records in mxRecords to the
570 | mxPatchFile. Adds required masters to mxPatchFile
571 | if they haven't been added yet. Records that fail to copy will be
572 | logged to mxFailures. Records that are copied successfully
573 | will be added to mxPatchRecords, and will be accessible
574 | through GetPatchRecord.
575 |
576 |
577 |
578 | function GetPatchRecord(i: integer): IInterface;
579 |
580 | Accesses records that were copied through the
581 | CopyRecordToPatch and CopyRecordsToPatch functions.
582 | Takes an index, i, to determine which record to load. You should
583 | use this function in conjunction with MaxPatchRecordIndex.
584 |
585 |
LoadRecords('LSCR');
586 | CopyRecordsToPatch;
587 | for i := 0 to MaxPatchRecordIndex do begin
588 | rec := GetPatchRecord(i);
589 | AddMessage('Patched '+Name(rec));
590 | end;
591 |
592 |
593 |
594 | function MaxPatchRecordIndex: integer;
595 |
596 | Gets the number of items in mxPatchRecords minus 1, the
597 | maximum index you can call GetPatchRecord with successfully.
598 | This is for use when looping through patch records.
599 |
600 |
601 |
Reporting
602 |
603 |
604 | procedure PrintMXPFReport;
605 |
606 | Prints a message to log the reporting on the number of copy operations
607 | performed, the number that were successful, and the number that failed.
608 |
609 |
LoadRecords('INGR');
610 | CopyRecordsToPatch;
611 | PrintMXPFReport;
612 |
613 |
614 |
Macros
615 |
616 |
617 | function MultiFileSelectString(sPrompt: String; var sFiles: String): Boolean;
618 |
619 | Uses MultiFileSelect from mteFunctions and outputs the result as a comma-separated string through sFiles. Returns false if the user cancelled the file selection.
620 |
621 |
bCanceled := not MultiFileSelectString('Select some files.', sFiles);
622 | if bCanceled then exit;
623 | SetInclusions(sFiles);
624 |
625 |
626 |
627 | procedure SetFileSelection(sFiles: String; bMode: Boolean);
628 |
629 | If bMode is true, calls SetInclusions on sFiles. If bMode is false, calls SetExclusions on sFiles.
630 |
631 |
sFiles := 'Skyrim.esm,Dawnguards.esm,Dragonborn.esm';
632 | SetFileSelection(sFiles, false); // excluding the files
633 | SetFileSelection(sFiles, true); // including the files
634 |
635 |
636 |
637 | procedure MultiLoad(sRecords: String);
638 |
639 | Accepts a comma-separated string of record signatures sRecords. Can also accept signature pairs. Calls LoadRecords for each record signature in sRecords, and calls LoadChildRecords for each record signature pair.
640 |
641 |
// load ARMO, ARMA, and WEAP records from the file selection
642 | MultiLoad('ARMO,ARMA,WEAP');
643 | // load REFR and ACHR children records from CELL record groups in the
644 | // file selection
645 | MultiLoad('CELL:REFR,CELL:ACHR');
646 |
647 |
648 |
649 | procedure QuickLoad(sFiles, sRecords: String; bMode: Boolean);
650 |
651 | Calls InitializeMXPF and DefaultOptionsMXPF. Then calls SetFileSelection with the input sFiles and bMode, and calls MultiLoad with the input sRecords.
652 |
653 |
// load all ACHR records from the CELL and WRLD record groups in all loaded
654 | // non-bethesda files.
655 | QuickLoad(mxBethesdaSkyrimFiles, 'CELL:ACHR,WRLD:ACHR', false);
656 | // loop through loaded records
657 | for i := 0 to MaxRecordIndex do begin
658 | rec := GetRecord(i);
659 | npc := LinksTo(ElementByPath(rec, 'NAME'));
660 | AddMessage('Found placed NPC '+Name(npc));
661 | end;
662 |
663 |
664 |
665 | procedure QuickPatch(sAuthor, sFiles, sRecords: String; bMode: Boolean);
666 |
667 | Calls InitializeMXPF and DefaultOptionsMXPF. Then calls PatchFileByAuthor with the input sAuthor. Then calls SetFileSelection with the input sFiles and bMode, and calls MultiLoad with the input sRecords. Finally, calls CopyRecordsToPatch.
668 |
669 |
// load all AMMO, ARMO and WEAP records from Skyrim.esm, and copy them to
670 | // a patch file with the author "Rebalance"
671 | QuickPatch('Rebalance', 'Skyrim.esm', 'AMMO,ARMO,WEAP', true);
672 | // loop through records in patch
673 | for i := 0 to MaxPatchRecordIndex do begin
674 | rec := GetPatchRecord(i);
675 | sig := Signature(rec);
676 | // double the armor rating of all armors
677 | if sig = 'ARMO' then begin
678 | oldValue := GetElementNativeValues(rec, 'DNAM');
679 | SetElementNativeValues(rec, 'DNAM', oldValue * 2.0)
680 | end
681 | // double the damage of all weapons and ammo
682 | else begin
683 | oldValue := GetElementNativeValues(rec, 'DATA\Damage');
684 | SetElementNativeValues(rec, 'DATA\Damage', oldValue * 2.0);
685 | end;
686 | end;
687 | FinalizeMXPF;
688 |
689 |
690 |
Links
691 |
692 |
693 | -
694 | The CreationKit wiki's
695 |
696 | TES5Edit Scripting Functions page. Provides a list of the
697 | scripting functions xEdit makes available.
698 |
699 | -
700 |
701 | Automation Tools for TES5Edit: a package of useful scripts for
702 | automating various TES5Edit tasks, and a good place to take
703 | inspiration from for script ideas and best practices.
704 |
705 | -
706 | The
707 | Merge Plugins xEdit Script: one of the most complex and most
708 | widely used xEdit scripts.
709 |
710 | -
711 | ThreeTen's
712 | NPC Visual Transfer Tool, a popular TES5Edit script for
713 | transferring NPC visual appearance.
714 |
715 | -
716 | DynDOLOD
717 | by Sheson: an extremely powerful TES5Edit script which makes use of
718 | TES5LodGen's LOD generation capabilities.
719 |
720 |
721 |
722 |
Changelog
723 |
724 |
725 | – August 31, 2015 –
726 | Docs
727 |
Initial release of MXPF.
728 |
729 |