Differences

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

--- dcx:event_library [2015/05/06 15:28] – created vic
+++ dcx:event_library [2026/06/22 12:21] (current) – external edit 127.0.0.1
@@ Line 1: / Line 1: @@
 === Event Libraries ===
-Usage: create sets of events that can be modularly offered to users of the simple editor
+There is no special editor. The advanced editor is used to create these.
-Now: VR creates a number of basic event libraries to enable basic scenario's without any very special rules
-Future: VR adds more libraries, some community modders manage to wrap their head around scripting events (in such a way that they can be used in a modular way)
-===Technical Details===
+It is important when designing this to provide the final user (in the simple editor) the options to configure and customize these event libraries.
-There is no special editor the advanced editor is used to create these.
+For example don't hardcode an event picture illustration for a message, but let the user specify one through a libvar or a table.
-It is important when designing this to provide the final user (in the simple editor) the options and documentation to configure these event libraries.
 This can be done by adding stringlists (tables) to the library and libvars... these can be given documentation and datatypes and will enable to give the end-user the ease-of-use to tailer the library for his scenario.
+It is very much recommended to always use the documentation buttons for libraries, libvars and stringlists (aka tables) so the end-user has some information on how to use them.
+===Rules when designing libraries===
+. Never store data in regimeslots or gameslots. Always store data in libvars of your own library. This makes sure it can function independently and will not get data mixed up with other libraries not of your writing. Keep in mind you can create these libvars on the fly just by writing to them using the appropriate exec.
+. Only use the old 9 maparea slots for calculations within an event. Never store data in them, always use hexlibvars of your own library for that purpose.
+. Where possible do not hardcode core variables. Make them accesible as libvars or stringlists of your own library. The end user will appreciate it. As will you when you re-use your event library for a different scenario.
+. Never hardcode the action card categories... The designer using your libary needs to be able to determine the category of each card your library uses or generates. This means having a global libvar accesible in which the end user can specify the category number of your cards. (take a look at the basic event library to see this approach in action). This is because there are only limited categories and the person using the Simple Editor determines the category names and which cards goes in which category (because he might be using a lot of libraries).
+. Never hardcode eventpictures in the messages generated by your events. Allow the user of your library to set them through a libvar.
+. Make sure if you are looping through actioncards for example in your events and deleting stuff that you only delete stuff from your library and not from others. Remember: the end user might be using your library in conjunction with other libraries.
 == Upon loading in simple editor ==
 Only the event, cards and event pictures info will be read from these libraries
+====How to script events?====
+This is something I have not documented yet. As it would be a huge topic. There are over 400 execs and checks and understanding their use requires to understand almost all data types in the engine.
+If there is a lot of interest in the Community Project I might start on this though.
+====Tutorial to create a very simple event library===
+Lets say we would like to have functionality that simulate some command & control problems for one or both of the sides in a scenario. How would we design an event library that would be capable to provide that functionality?
+Before we start lets list what we'll need to do:
+* A regime libvar that switches this functionality on/off: CommandProblemsEnabled = yes/no
+* A regime libvar that specifies the % a HQ suffers C&C problems: CommandProblemsChance = numeric (0-100)
+* A regime libvar that specifies the basic AP its units will lose: CommandProblemsFixedAPLoss = numeric (0-100)
+* A regime libvar that specifies a random ammount of AP its units will lose: CommandProblemsRandomAPLoss = numeric (0-100)
+* A 'turn event' that when the regime in question has its regimeLibVar CommandProblems set to 'yes' loops through all HQs to test them for Command problems.
+Thats it. It will do the job. No chrome, but I am keeping it simple in this tutorial.
+===Step A: Creating an event library and libvars===
+Make sure you have the advanced editor enabled. In the main menu click on the 'advanced editor' button and specify a smallest map size as possible.
+{{:dcx:evlib7.jpg|}}
+Then once in the advanced editor go to the settings tab and then to the 'Import and Other settings' tab and set the ruleset to 'VR'
+This is important as it tells the Simple editor that your event library is compatible with the default VR ruleset.
+{{:dcx:evlib1.jpg|}}
+Then go to the lib tabsheet.
+{{:dcx:evlib2.jpg|}}
+There we do the following.
+. Create a new library
+. Set the name of this library. Remember it has to be a unique name (call it something specific, not just 'my library' or something similar)
+. Add 4 libvars
+. Set each libvar to 'regime libvar' type and give it a propper name thats unique and describes already what it does.
+Optionally you can also give a description field to each libvar and to the library as a whole. This is RECOMMENDED because you'd like other designers to make use of your library as well. Thats the whole philosophy behind the Community Project.
+Thats it. We have defined our library and libvars. Now we go to the event editor.
+===Step B: Adding the event scripting===
+{{:dcx:evlib3.jpg|}}
+In the event editor you do the following.
+. Add a new event.
+. Assign the event to your "Command Problems Library".
+. Name the event
+. Set the execution type for the event to 'late start turn'. 'Late' and not 'Early' because we want to modify the AP of the units after they are set and before the player gets access to moving them.
+===Step C: Scripting the event===
+Then I script the following code:
+<code>
+)    ' event code is going to come here
+)    SETVAR: TempVar1 = CheckTurn
+)    '
+)    SETVAR: TempVar2 = CheckLibVarRegime(TempVar1, 'Command Problems Library', 'CommandProblemsEnabled')
+)    SETVAR: TempVar3 = CheckLibVarRegime(TempVar1, 'Command Problems Library', 'CommandProblemsChance')
+)    SETVAR: TempVar4 = CheckLibVarRegime(TempVar1, 'Command Problems Library', 'CommandProblemsFixedAPLoss')
+)    SETVAR: TempVar5 = CheckLibVarRegime(TempVar1, 'Command Problems Library', 'CommandProblemsRandomAPLoss')
+)    '
+)    SETVAR: TempString1 = ''
+)    '
+)   CHECK: TempVar2 > 0
+)     ' If CommandProblemsEnabled=Yes we arrive here
+)     LOOPER: TempVar6 FROM 0 TO CheckTotalUnits
+)       '
+)       CHECK: CheckUnitHistoricalID(TempVar6) > 0
+)         CHECK: CheckUnitIsHQ(TempVar6) > 0
+)           CHECK: CheckUnitOwner(TempVar6) == TempVar1
+)             '
+)             SETVAR: TempVar7 = CheckRandomPercent
+)             CHECK: TempVar3 > TempVar7
+)               ' If random roll 0-100 is below CommandProblemsChance for this HQ a command problem occures
+)               '
+)               SETVAR: TempVar10 = TempVar5
+)               SETVAR: TempVar10 * CheckRandomPercent
+)               SETVAR: TempVar10 / 100
+)               SETVAR: TempVar10 + TempVar4
+)               SETVAR: TempVar11 = 0
+)               SETVAR: TempVar11 - TempVar10
+)               ' tempvar11 has the AP loss calculcated for units under this HQ (or hq itself)
+)               SETVAR: TempString1 + CheckUnitName(TempVar6)
+)               SETVAR: TempString1 + ' has suffered '
+)               SETVAR: TempString1 + TempVar11
+)               SETVAR: TempString1 + 'AP due to command problems.'
+)               SETVAR: TempString1 + ReturnCRLF
+)               '
+)               LOOPER: TempVar8 FROM 0 TO CheckTotalUnits
+)                 '
+)                 SETVAR: TempVar9 = 0
+)                 CHECK: CheckUnitHQ(TempVar8) == TempVar6
+)                   SETVAR: TempVar9 = 1
+)                 END CHECK
+)                 CHECK: CheckUnitIsHQ(TempVar8) > 0
+)                   SETVAR: TempVar9 = 0
+)                 END CHECK
+)                 CHECK: TempVar6 == TempVar8
+)                   SETVAR: TempVar9 = 1
+)                 END CHECK
+)                 '
+)                 CHECK: TempVar9 == 1
+)                   ' This unit is suffering Command Problems
+)                   EXECUTE: ExecUnitApModify(TempVar8, TempVar11, -1, -1)
+)                 END CHECK
+)                 '
+)               END LOOPER
+)               '
+)             END CHECK
+)             '
+)           END CHECK
+)         END CHECK
+)       END CHECK
+)       '
+)     END LOOPER
+)     '
+)     CHECK: CheckStringLength(TempString1) > 0
+)       EXECUTE: ExecMessage(TempVar1, -1, -1, -1)
+)     END CHECK
+)     '
+)   END CHECK
+</code>
+===Step D: Save the event library===
+{{:dcx:evlib4.jpg|}}
+Save your work with the .dcxevlib extension.
+And thats it.
+In the final Step E i am just going to show how it looks like to the end-user when he loads your event library.
+===Step E: In the Simple Editor & In-Game===
+{{:dcx:evlib6.jpg|}}
+In the Simple Editor you or an end-user can load your event library and configure it (as shown in the example above) for one or more regimes.
+Also note that the contents of the library are correctly listed as 4 libvars and 1 event.
+Then finally when in-game when in-game the player will get reports like this one:
+{{:dcx:evlib8.jpg|}}
+It is important to check if your event libraries work properly before distributing them.
+Don't forget to use the description fields for the library itself and its libvars and/or stringlists (tables for end-user).
+Thats it! A working and tested library ready for use or sharing with other designers.
+===Tutorial library===
+Here you can download the library created in the tutorial above:
+[[http://www.vrdesigns.nl/privatepatch/CommandProblems.zip|CommandProblems.zip]]