?WikiName? - Souls Modding Wiki

User Tools

Site Tools

Trace:
tutorial:mattscript-documentation

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
tutorial:mattscript-documentation [2025/02/24 23:05] – [MattScript Documentation] admintutorial:mattscript-documentation [2025/02/27 00:44] (current) – admin
Line 2: Line 2:
 Authors: thefifthmatt Authors: thefifthmatt
 ===== Preamble ===== ===== Preamble =====
-MattScript is an uncreatively named extension to DarkScript3 developed by thefifthmatt which adds additional syntax for control flow and condition expressions for writing advanced scripts with ease. It can be activated in events by defining them with ''$Event'' instead of ''Event''. See [[tutorial:learning-how-to-use-emevd|Learning How To Use EMEVD]] for an overall tutorial of EMEVD, and [[tutorial:intro-to-elden-ring-emevd|Intro to Elden Ring EMEVD]] for a detailed walkthrough of MattScript in Elden Ring.+MattScript is an uncreatively named extension to DarkScript3 developed by thefifthmatt which adds additional syntax for control flow and condition expressions for writing advanced scripts with ease. It can be activated in events by defining them with ''$Event'' instead of ''Event''. See [[tutorial:learning-how-to-use-emevd | Learning How To Use EMEVD]] for an overall tutorial of EMEVD, and [[tutorial:intro-to-elden-ring-emevd | Intro to Elden Ring EMEVD]] for a detailed walkthrough of MattScript in Elden Ring.
  
 On its own, DarkScript3 works by evaluating a JavaScript file which calls many instruction functions. Each instruction function adds an instruction to an event. Inside of ''Event''s, you can also use regular JavaScript, like helper functions and loops. On its own, DarkScript3 works by evaluating a JavaScript file which calls many instruction functions. Each instruction function adds an instruction to an event. Inside of ''Event''s, you can also use regular JavaScript, like helper functions and loops.
Line 10: Line 10:
 For example, an ''$Event'' might have this code: For example, an ''$Event'' might have this code:
  
-<code>+<code JavaScript>
 $Event(11005000, Default, function(entityId, objEntityId, animationId) { $Event(11005000, Default, function(entityId, objEntityId, animationId) {
     if (ThisEventSlot()) {     if (ThisEventSlot()) {
Line 24: Line 24:
 When saving a file, it is converted into this equivalent ''Event'' which is then executed by DarkScript3: When saving a file, it is converted into this equivalent ''Event'' which is then executed by DarkScript3:
  
-<code>+<code JavaScript>
 Event(11005000, Default, function(entityId, objEntityId, animationId) { Event(11005000, Default, function(entityId, objEntityId, animationId) {
     SkipIfEventFlag(2, OFF, TargetEventFlagType.EventIDAndSlotNumber, 0);     SkipIfEventFlag(2, OFF, TargetEventFlagType.EventIDAndSlotNumber, 0);
Line 51: Line 51:
 As a simple example, suppose there is an area in the map, and as long as a fight is active, we want to slowly auto-heal the player as long as they are under 70% HP and in that area. A simple version of that might be as follows: As a simple example, suppose there is an area in the map, and as long as a fight is active, we want to slowly auto-heal the player as long as they are under 70% HP and in that area. A simple version of that might be as follows:
  
-<code>+<code JavaScript>
 $Event(13705010, Restart, function() { $Event(13705010, Restart, function() {
     WaitFor(InArea(10000, 3704310));     WaitFor(InArea(10000, 3704310));
Line 69: Line 69:
 Finally, condition functions can be combined using the logical operators ''&&'' and ''||''. A more standard way of writing the event might be as follows: Finally, condition functions can be combined using the logical operators ''&&'' and ''||''. A more standard way of writing the event might be as follows:
  
-<code>+<code JavaScript>
 $Event(13705010, Restart, function() { $Event(13705010, Restart, function() {
     WaitFor(InArea(10000, 3704310) && HPRatio(10000) < 0.7);     WaitFor(InArea(10000, 3704310) && HPRatio(10000) < 0.7);
Line 81: Line 81:
 One useful trick for dealing with boolean logic is De Morgan's law, which is a way to rewrite conditions without changing behavior. In general, ''!(a && b && c)'' (not all of them true) can be rewritten as ''!a || !b || !c'' (at least one of them false), and ''!(a || b || c)'' (none of them true) can be rewritten as ''!a && !b && !c'' (all of them false). Basically, switch the inner/outer ''!''s and switch the operator. This applies to events like this: One useful trick for dealing with boolean logic is De Morgan's law, which is a way to rewrite conditions without changing behavior. In general, ''!(a && b && c)'' (not all of them true) can be rewritten as ''!a || !b || !c'' (at least one of them false), and ''!(a || b || c)'' (none of them true) can be rewritten as ''!a && !b && !c'' (all of them false). Basically, switch the inner/outer ''!''s and switch the operator. This applies to events like this:
  
-<code>+<code JavaScript>
 $Event(9182, Default, function() { $Event(9182, Default, function() {
     EndIf(!CharacterType(10000, TargetType.Alive));     EndIf(!CharacterType(10000, TargetType.Alive));
Line 94: Line 94:
 Which is equivalent to the following: Which is equivalent to the following:
  
-<code>+<code JavaScript>
 $Event(9182, Default, function() { $Event(9182, Default, function() {
     EndIf(!CharacterType(10000, TargetType.Alive));     EndIf(!CharacterType(10000, TargetType.Alive));
Line 109: Line 109:
 An even more fromsoft-ian way of structuring the 70% HP example might be as follows, which brings us to condition variables: An even more fromsoft-ian way of structuring the 70% HP example might be as follows, which brings us to condition variables:
  
-<code>+<code JavaScript>
 $Event(13705010, Restart, function() { $Event(13705010, Restart, function() {
     fightOver = EventFlag(13700860);     fightOver = EventFlag(13700860);
Line 124: Line 124:
 For the most part, ''$Event'' hides details of how condition groups are structured. Expressions using ''||'' and ''&&'' are converted to use them, like this: For the most part, ''$Event'' hides details of how condition groups are structured. Expressions using ''||'' and ''&&'' are converted to use them, like this:
  
-<code>+<code JavaScript>
 $Event(13705011, Restart, function() { $Event(13705011, Restart, function() {
     WaitFor(InArea(10000, 3704310) && HPRatio(10000) < 0.7);     WaitFor(InArea(10000, 3704310) && HPRatio(10000) < 0.7);
Line 132: Line 132:
 This is compiled down to this low-level representation: This is compiled down to this low-level representation:
  
-<code>+<code JavaScript>
 Event(13705011, Restart, function() { Event(13705011, Restart, function() {
     IfInoutsideArea(AND_01, InsideOutsideState.Inside, 10000, 3704310, 1);     IfInoutsideArea(AND_01, InsideOutsideState.Inside, 10000, 3704310, 1);
Line 142: Line 142:
 Another way of writing the event using an explicit condition variable would be like this. (Note: it is strongly recommended to use the ''&&'' expression instead, because explicit groups aren't automatically reused and there is a finite number of total groups.) Another way of writing the event using an explicit condition variable would be like this. (Note: it is strongly recommended to use the ''&&'' expression instead, because explicit groups aren't automatically reused and there is a finite number of total groups.)
  
-<code>+<code JavaScript>
 $Event(13705011, Restart, function() { $Event(13705011, Restart, function() {
     areaLowHp &= InArea(10000, 3704310);     areaLowHp &= InArea(10000, 3704310);
Line 165: Line 165:
 A common usage of condition variables is to have conditions whose definitions can change based on event parameters, like this excerpt from the DS3 fog gate traversal event: A common usage of condition variables is to have conditions whose definitions can change based on event parameters, like this excerpt from the DS3 fog gate traversal event:
  
-<code>+<code JavaScript>
 $Event(20005800, Restart, function(eventFlagId, areaEntityId, areaEntityId2, eventFlagId2, actionButtonParameterId, chrEntityId, eventFlagId3, areaEntityId3) { $Event(20005800, Restart, function(eventFlagId, areaEntityId, areaEntityId2, eventFlagId2, actionButtonParameterId, chrEntityId, eventFlagId3, areaEntityId3) {
     ...     ...
Line 180: Line 180:
 Plenty of other interesting uses are possible, like this Sekiro event. Condition variables can basically be used anywhere a condition is expected, not just in ''WaitFor''s. Plenty of other interesting uses are possible, like this Sekiro event. Condition variables can basically be used anywhere a condition is expected, not just in ''WaitFor''s.
  
-<code>+<code JavaScript>
 $Event(11105130, Restart, function() { $Event(11105130, Restart, function() {
     SetEventFlag(11100130, OFF);     SetEventFlag(11100130, OFF);
Line 202: Line 202:
 In this case, you could also implement it as follows, although this uses slightly more condition groups behind the scenes. In this case, you could also implement it as follows, although this uses slightly more condition groups behind the scenes.
  
-<code>+<code JavaScript>
 $Event(11105130, Restart, function() { $Event(11105130, Restart, function() {
     if ((!EventFlag(8302) && EventFlag(11100301)) || (EventFlag(8302) && EventFlag(11100480))) {     if ((!EventFlag(8302) && EventFlag(11100301)) || (EventFlag(8302) && EventFlag(11100480))) {
Line 253: Line 253:
 A toy example of their use: A toy example of their use:
  
-<code>+<code JavaScript>
 $Event(9194, Default, function() { $Event(9194, Default, function() {
     GotoIf(L0, EventFlag(6006));     GotoIf(L0, EventFlag(6006));
Line 267: Line 267:
 Becomes: Becomes:
  
-<code>+<code JavaScript>
 Event(9194, Default, function() { Event(9194, Default, function() {
     GotoIfEventFlag(Label.LABEL0, ON, TargetEventFlagType.EventFlag, 6006);     GotoIfEventFlag(Label.LABEL0, ON, TargetEventFlagType.EventFlag, 6006);
Line 300: Line 300:
 Const variable declarations in events are permitted. An example of constants and simple expressions: Const variable declarations in events are permitted. An example of constants and simple expressions:
  
-<code>+<code JavaScript>
 $Event(13105265, Restart, function() { $Event(13105265, Restart, function() {
     const bossEntity = 3100395;     const bossEntity = 3100395;
Line 316: Line 316:
 For loops are specially processed by MattScript. The loop definition itself is retained as pure JS, but the contents are compiled. Regular for-loops (with ''let'' variables) and for-of-loops (with ''const'' variables) are supported. For instance, this lets you define an array of enemies, and make some combined condition from them. For loops are specially processed by MattScript. The loop definition itself is retained as pure JS, but the contents are compiled. Regular for-loops (with ''let'' variables) and for-of-loops (with ''const'' variables) are supported. For instance, this lets you define an array of enemies, and make some combined condition from them.
  
-<code>+<code JavaScript>
 $Event(13105266, Restart, function() { $Event(13105266, Restart, function() {
     const bossEntities = [3100395, 3100398, 3100399];     const bossEntities = [3100395, 3100398, 3100399];
Line 331: Line 331:
 In cases where you're repeating a series of if statements which require condition variables, this is fairly difficult even without MattScript. You can use a no-op condition group reset in between iterations. In cases where you're repeating a series of if statements which require condition variables, this is fairly difficult even without MattScript. You can use a no-op condition group reset in between iterations.
  
-<code>+<code JavaScript>
 $Event(13105267, Restart, function() { $Event(13105267, Restart, function() {
     WaitFor(EventFlag(13105265));     WaitFor(EventFlag(13105265));
Line 350: Line 350:
 Typed event initializations allow for event declarations and initializations where the event parameters have names and types. They are not part of MattScript but they do preprocess the source file using the same parser routine. Typed event initializations allow for event declarations and initializations where the event parameters have names and types. They are not part of MattScript but they do preprocess the source file using the same parser routine.
  
-<code>+<code JavaScript>
 // Old-style events use parameter names starting with X // Old-style events use parameter names starting with X
 $Event(73791090, Default, function(X0_1, X1_1, X2_1, X3_1, X4_4, X8_4, X12_1)) { ... }); $Event(73791090, Default, function(X0_1, X1_1, X2_1, X3_1, X4_4, X8_4, X12_1)) { ... });
tutorial/mattscript-documentation.1740438301.txt.gz · Last modified: by admin

Page Tools

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki