Entry posted by Feliks
2560 views
Welcome ladies and gentleman once again to the CANS API blog post. With the latest build (0.18) there are some massive changes. In general implementation from the old post will still work but quite a bit of it is irrelevant and no longer necessary. So to save you some time, the game some memory, and better explain things from the last one, this has been rewritten.
I'm going to break this up into sections for everyone's convenience.
1. How Does the C.A.N.S. Framework Actually Work?
Now you see, I'm actually really proud of that, but it's also very complicated, so unless you're legitimately interested probably don't open this spoiler.
If you've looked through the latest release you've probably noticed something about C.A.N.S. compared to earlier beta versions, there are only three scripts as opposed to the seven or eight in earlier beta builds. If you look in the Creation Kit or TESVedit you'll notice there are only four new forms. Well, there are six but three of them exist only for backwards compatibility reasons.
And yet, despite minimal impact this is an immensely powerful framework.
Very simply one of the quests and one of the scripts are the MCM, you know what these do, you've seen them before, it's not the interesting part.
The fun part comes with the other two scripts. The Framework and Core scripts.
The Framework is what other mods interact with, it controls everything and resides in the other quest in the Creation Kit. It enables coordination between mods and nodes, and controls the instances of the Core Script. There is only one instance of the Framework in any game.
The Core Script (and this is where things get interesting) resides in the magic effect created in the creation kit, which is applied by the spell. The Core script handles changing node sizes and updating data. The original versions of CANS handled everything with persistent magic effects that would constantly be attached to actors and update when necessary, however this posed a problem. Due to limitations in the Skyrim Engine active effects have a nasty habit of disappearing from NPC's when the NPC is not loaded, essentially meaning that every now and then the game would just shoot CANS in the foot and ruin everything.
To solve this problem the Magic Effect now no longer needs to be consistent. No data is stored longterm in the magic effect so if it disappears no problem. All data for NPCs is now stored via StorageUtil, allowing for easy access without persistent effects.
What happens when a request to update a size is sent is the Framework first receives the request, and then creates an active effect on the actor. The effect then pings the framework so that the framework can access that specific instance of the script (a problem I was told could not be solved with this kind of dynamic effect) and trigger the update, passing along the requested node, size, and mod. The Effect then takes this data, updates the sizes stored via storage util on that specific actor, updates the size as needed via whichever method you chose, and once the update is complete, dispels itself, freeing the stored slot in the framework to apply yet another effect.
This all works in concert to create an adaptable system theoretically capable of handling more than a thousand updates at once, all with no persistent magic effects and easily uninstallable via one click in the MCM.
2. What are the Limitations of C.A.N.S.?
The biggest issue (that if there is demand for a solution will be rectified in version 2.0 and later) is that it only works on the Belly, Breast, and Butt nodes. Now, if using a skeleton with six breasts (at least one human and werewolf body/skeleton exist) it will scale all of them together. If these have users who complain this can be modified.
As for actual limitations:
It can only support 384 registered mods at any given time.
Only 1024 node updates can be active at any given time, however there is an overflow catch that allows more to be queued, in special testing circumstances nearly 3,000 were queued at a single time with no dropped requests but this caused substantial lag dues to the amount of scripts running.
Depending on script lag, certain calculation settings may take a noticeable amount of time to finish.
Now for disclaimers:
I personally guarantee that the 384 mod limit will never be reached, ignoring the fact that only 256 .esp files can be active it would need to be 384 mods that change node sizes.
Barring poor design no mod would realistically call 1024 node updates at a time, imagine how much of Skyrim's population that would be to track at once. Additionally, even if it does CANS will most likely continue to process requests thanks to the overflow check
The script lag limitation is not something CANS can control and if it is an issue you will experience you're most likely already used to a little bit of it. (CANS will not contribute significantly to lag)
tl;dr: Under normal circumstances you won't ever have to deal with them; and CANS does not contribute significantly to lag
3. How do I Make a Mod or Patch CANS Compatible?
Now this is the bread and butter of this post, why most of you are here, and hopefully something that brings us into a new era of inflation or pregnancy based mods.
Full API and explanation within the spoiler
Note: It is assumed you have a basic understanding of Papyrus and the Creation Kit
Step 0: Important variables and mechanics
The two most important things when working your mods with CANS are the strings you will use for the Mod's name and the category.
Mod Name: This is the key you will use to get and modify your values in CANS, as well as register and unregister. It does not necessarily need to be the mod's name but as the user will be able to see it in regards to some settings it is highly recommended you keep it short enough to display in an MCM and easily identifiable as your mod.
Category: There are six categories in CANS, Pregnancy, Cumflation, Milking, Inflation, Miscellaneous, and Uncategorized.
These categories are handled differently in some calculation settings and make it easier for users to modify values.
Category descriptions with specific string values for CANS:
Pregnancy: your mod is primarily centered on pregnancy. Ex: Estrus Chaurus, Soul Gem Oven
Passed as "Pregnancy"
Cumflation: your mod is primarily focused on inflation due to semen. Ex: Fell 'er up
Passed as "Cumflation"
Milking: Your mod is primarily centered around milking or milk maids. Ex: Milk Mod Economy
Passed as "Milking"
Inflation: Your mod is centered around the specific fetish of inflation, I am assured that this is its own category and that no mods currently exist for it (?)
Passed as "Inflation"
Miscellaneous: Your mod does not obviously fit into any of these categories
Passed as "MiscCat"
Uncategorized: You were too lazy to set this up or for some reason wrote your mod for an earlier version of CANS.
Passed as "UnCat"
Step 1: Setting up Properties
To use CANS it is important that you have access to the Instance of the CANS_Framework.
To do so simply create a property in your script of type "CANS_Framework" and use the property window to point it too the instance attached to the "CANS" quest.
The finished code should look something like this:
CANS_Framework Property CANS Auto;
Further code examples will assume this is how the property was set.
Note: a method for retrieving the Instance for soft dependencies is being looked into for the 1.0.1 release, but for now existing methods should work.
Step 2: Register your mod with CANS
This is the first step in modifying the sizes of a target actor. To call this function properly you need three items, the target as type Actor, a unique string to use consistently for your mod, and the Category.
The function to call is RegisterMyMod which returns a boolean value, true if the mod was registered properly, false if it was not.
You call the function like so:
Bool Registered = False;Registered = CANS.RegisterMyMod(Target, "MyMod", "Milking");
In this example Target is the actor you wish to modify of type Actor, MyMod is the mod name, and Milking is the category. Registered will be set to true or false after registration is attempted.
Step 3: Call an update
This is why you're here after all, the actual changing of sizes, so let's get to it.
Now in it's current version CANS only support three kinds of nodes, Belly, Breast, and Butt. To simplify this there are three functions, one for each set.
The Functions are simply Belly() Breast() and Butt(), because anything else is over complication, and are called as follows:
CANS.Belly(Target, "MyMod", 2.0);CANS.Breast(Target, "MyMod", 2.25);CANS.Butt(Target, "MyMod", 2.5);
As you can see, each accepts the same three arguments, Target as type Actor, the mod name as type string, and the node size as type float. Additionally the functions return an int value with the following key:
0: Functioned as expected, update called
1: Override in place from another mod. Size stored but not updated
2: Terrible error has occurred. Please wait for some time and attempt the update once again. Size has been updated but not the NiO size.
Step 4: Checking Sizes
So you're at a point where you need to make sure the targets breasts or butt is the right size, the problem CANS was originally created to solve.
It is very important that you check the size through CANS, which will return only the size you have passed and not the overall size because the two are likely not the same.
As with updating the nodes there are three separate functions, called as follows:
Float BellySize = CANS.ReturnBelly(Target, "MyMod");Float BreastSize = CANS.ReturnBreast(Target, "MyMod");Float ButtSize = CANS.ReturnButt(Target, "MyMod");
Each function takes two arguments, the target as type actor (shocker, right?) and the modname as type string. These functions return float values.
Step 5: Unregister your mod with CANS
The time has come for your mod to stop working its magic, either it is being uninstalled, the dragonborn has given birth, they're all emptied out, or some other reason you have for no longer modifying node sizes. It is important to remove your mod from CANS so that it no longer takes up one of the available mod slots.
Unregistering is just as easy as registering but with two options, removing your mod from a single target or completely from CANS.
The first function to remove your mod from a single actor is executed as follows:
CANS.UninstallMyMod(Target, "MyMod");
With Target as type actor and the modname as a string, as I'm sure you guessed.
To remove your mod globally from CANS:
CANS.UninstallMod("MyMod");
This is called with only the modname as a string and executes a global removal.
Both functions return a boolean value of true if the uninstallation is successful.
Closing Remarks:
STORE YOUR MOD NAME STRING AS A VARIABLE AND USE THAT IN FUNCTION CALLS. It is case sensitive and any typo could begin causing errors or unexpected behavior.
Every function returns a value, use that to prevent errors, I believe every case is covered and theoretically there would be no errors but I'm not perfect... yet.
For more information, documentation, or explanation refer to the source codes, I keep them well documented.
4. Advanced Features/Tips & Tricks
Here are a few neat features advanced modders may want to take advantage of.
Mod Names
You'll notice the mod name is something you set specifically and not something actually tied to your mod. In fact, CANS does nothing to check anything else. This makes it possible for mods to alter other mods sizes for an interesting take on soft dependency or, more interestingly, the ability for a single mod to contain multiple effects or quests modifying node sizes, they just need to be registered differently.
Overrides
This is a highly advanced feature that if used improperly could cause serious issues, please refer to CANS_Framework.psc for further documentation
Overrides were implemented with the idea that certain mods may want quest scenes or certain events to play out with a specific size in mind, allowing you to set a size in CANS that will appear regardless of other sizes set by mods. These can be disabled or removed by players but not by other mods.
IT IS VERY IMPORTANT TO REMEMBER TO REMOVE YOUR OVERRIDES SO THAT CANS CAN FUNCTION AS INTENDED
The functions are called exactly the same way the regular size functions are called, but as OverrideBelly() OverrideBreast(), or OverrideButt(). For example:
CANS.OverrideButt(Target, "MyMod", 2.0);
This would apply an override to Target from "MyMod" at a size of 2.0
To end the override the function is EndOverrideXXX() for example:
CANS.EndOverrideButt(Target, "MyMod");
Which will return a boolean value if it was ended. If it returns false, odds are another mod has an override in place.
NOTE: If overrides are disabled or another mod has an override in place the override function corrects for this on it's own, triggering a regular update before returning a value.
There you have it folks, the updated for 1.0 C.A.N.S. Framework API/Implementation
0 Comments
Recommended Comments
There are no comments to display.