With custom receptions officially supporting custom passives, page abilities and dice abilities via C# assembly and DLL creation, it’s finally time to start unlocking the true potential of Ruina modding.
 
 

“I wasn’t anyone special. I wasn’t richer than most people, and I didn’t really have special talent in any field.”

Official custom reception support came out and with it, a tool that makes designing a custom reception easy. Except for one part; passives or abilities that aren’t already in the game. These have always required the use of assembly when using BaseMods or any other modding middleman, and after official support was added, this has not changed. Still, there is no resource for how to go about doing such a vital thing that forms the basis of your mod’s individuality or identity, so this guide serves to be a basic gateway into such.
 
 
As a warning, I have little to no actual experience modding Ruina itself, just a solid amount of C# experience, this will focus more on getting an absolute beginning up to speed on how to make a basic assembly for use in their mod. This will not teach you the full potential of making an assembly for Ruina, I’ll leave that up to the experts.
 
 
 

“Heck, they might even be better than the surgeries and tools most workshops have to offer.”

As a preface, this guide will refer a lot to Project Moon’s official guide on making an assembly, which you can find here:
 
 
https://docs.google.com/presentation/d/1mJKbasEplw8Kvr4uwG6mvfHF8Z9ebM4AoAYCn82CNW4/ – [google.com] 
 
 
A cursory glance will tell you a lot about what’s missing; basically everything relating to the actual coding itself. This first part will focus on elaborating on the guide, and then moving onto the code reference.
 
 
The very first thing you might need is a way to make the DLL file that Ruina will use to insert your custom stuff into your mod. This is the Visual Studio part of PM’s guide, as well as the .NET framework.
 
 
You can download Visual Studio here. – [microsoft.com]  Be sure to grab Community 2019. When you install it, you should also have the option to install the .NET framework dev tools. You’ll need it to compile the correct assembly.
 
 
You’ll also likely need a microsoft account, as the free version of Visual Studio ceases function without one after a while.
 
 

 
 
The PM guide does a good job at telling you how to start once you do have Visual Studio. Clicking ‘Create a New Project’ brings you to a screen much like this one. Specifying ‘C#’ and scrolling will help you find the necessary template to begin. Loading Visual Studio may take a lot of time, be patient.
 
 

 
 
You can find Ruina’s local files by right clicking it in your library and hitting Browse Local Files. Be sure that you don’t move or use a copy of the DLL instead, there are many references that are made that are vital to the building of your own.
 
 

 
 
Once that’s done, you should have something like this presented to you. Congratulations, you may begin coding.
 
 
 

“And in that story, comedy and tragedy intertwine in a complex way.”

Passives? Card Abilities? Dice???

 
 
This is where PM’s guide fails to elaborate the most. When it says ‘Write C# code’ you might wonder how to do so. There is at least one area the guide teaches us that’s important for getting started.
 
 

 
 
When it comes to starting a block of code for any ability, you start it with public class and then the name of what you plan on making, which the guide illustrates. So public class DiceCardAbility_{ability_name} : DiceCardAbilityBase will declare a dice ability.
 
 
You may replace the curly braces (the ‘{}’) and anything in between them with whatever name you want, but make sure it is purely alphanumerical, with or without underscores. An example found in a sample source code file in Ruina’s game folders is public class DiceCardAbility_projmoon_custom_debuf : DiceCardAbilityBase
 
 

Dice Ability

 
 
The effect of a single dice on a given combat page. An example of a dice ability:
 
 

 
 
Here, it is On Clash Win: Restore 1 Light
 
 

Card Ability

 
 
The effect performed by playing the page itself. An example of a card ability:
 
 

 
 
Another popular example would be On Combat Start
 
 

Character Passive

 
 
A passive ability on a set key page. An example of a character passive:
 
 

 
 

The Name and Description

 
 
The game, of course, has UI elements that tell you what effects do when they are triggered, and how to trigger them, just like in the screenshots above. While a lot of code of specific to a certain field, all three use a description and it is defined as public static string Desc
 
 

 
 
What’s in between the quotation marks is what’s displayed in game. For character passives, you can also use public static string Name to specify the passive’s name.
 
 

public override void???

 
 
The basis for every ability is a conditional. Whether it’s On Hit, On Combat Start or even When using combat pages.etc, there is a condition that triggers the effect. public override means that the assembly code is ‘overriding’ some of Ruina’s base mechanics to insert it’s own. That’s a massive generalization that will get programmers angry with me, but bear with me, pretend you’re 12.
 
 
The void part is a little trickier, but essentially, if the condition isn’t returning a value, then it must be void. If it IS returning a value, then it must be the same data type as what you’re returning.
 
 

 
 
In the example above, we are returning a number, so instead of void, use int. This is a rare case, usually, however, but it explains why the word is necessary.
 
 
 

“If she could make this more painful for us, she would have already.”

Enough with the preamble, I wanna code

 
 
Visual Studio does a lot to help you figure functions out, as the assembly you added as a reference contains all the keywords you’d need, and as you’re typing, it’ll help you complete your code and even offer suggestions, but for people who don’t know where to start or are using an IDE like this for the first time, it can be daunting. That’s what this guide is ultimately for.
 
 

Dice Ability Conditionals

 
 
You can find all the conditionals for a Dice Ability under DiceCardAbilityBase in the ObjectBrowser, but here’s a list of common ones and what they do exactly.
 
 

• OnSucceedAttack()
   
   
   
  On Hit in game. Generally only useful for offensive dice. When the dice deals damage, this condition is fulfilled.
• OnSucceedAttack(BattleUnitModel)
   
   
   
  The same as the previous, but you can specify BattleUnitModel target here to immediately have access to actions pertaining to the character the damage went to.
• OnWinParrying()
   
   
   
  On Clash Win in game. If this dice wins in a clash against another dice, regardless of what kinds, this condition is fulfilled.
• OnLoseParrying()
   
   
   
  On Clash Lose in game. Similar to above, but this dice must lose.
• OnDrawParrying()
   
   
   
  On Clash Draw in game. Similar to above, but both dice must be precisely equal.
• OnWinParryingDefense()
   
   
   
  On Defense in game. Similar to On Clash Win but is only fulfilled on a block dice that successfully deflects.
• BeforeRollDice()
   
   
   
  Fulfilled before the dice is actually rolled, but after prior combat.

 
 

Card Ability Conditionals

 
 
You can find all the conditionals for a Card Ability under DiceCardSelfAbilityBase in the ObjectBrowser, but here’s a list of common ones and what they do exactly.
 
 

• OnUseCard()
   
   
   
  On Use in game. The condition is fulfilled the moment the page enters combat, just before it’s dice are rolled. If it only has counter dice (or no dice) then it’s fulfilled when the page would take it’s turn according to where it was in the order of the speed dice in the scene.
• OnStartBattle()
   
   
   
  On Combat Start in game. This condition fulfilled when the player initiates the scene’s combat phase.
• OnStartOneSideAction()
   
   
   
  On One-Sided Attack in game. The condition is fulfilled if this page does not clash with another page but still enters combat.
• OnStartParrying()
   
   
   
  On Clash Start in game. This condition is fulfilled when it enters combat and clashes with another page.
• OnEndBattle()
   
   
   
  On Combat End in game. This condition is fulfilled when the combat phase ends, just before the next scene starts.
• OnSucceedAttack()
   
   
   
  On Hit in game. This condition is fulfilled when any offensive dice on this page deals damage.

 

Character Passve Conditionals

 
 
You can find all the conditionals for a Character Passive under PassiveAbilityBase in the ObjectBrowser, but here’s a list of common ones and what they do exactly.
 
 

• AfterGiveDamage(int)
   
   
   
  Fulfilled when dealing damage. int is the amount of damage dealt.
• AfterTakeDamage(BattleUnitModel, int)
   
   
   
  Fulfilled when taking damage. BattleUnitModel is the attacker while int is the damage taken.
• OnBreakState()
   
   
   
  Fulfilled when the character is staggered.
• BeforeGiveDamage(BattleDiceBehavior)
   
   
   
  Fulfilled just before successfully dealing damage. BattleDiceBehavior is the rolled dice.
• OnDrawCard()
   
   
   
  Fulfilled whenever a page is drawn. This happens at the beginning of every scene, unless the character is staggered, as well as whenever a combat page or character passive draws one.
• OnKill(BattleUnitModel)
   
   
   
  Fulfilled whenever the character lands a finishing blow on another. BattleUnitModel is the character that died.
• OnLevelUpEmotion()
   
   
   
  Fulfilled when the character’s emotion level rises.
• OnMakeBreakState(BattleUnitModel)
   
   
   
  Fulfilled whenever the character staggers another character. BattleUnitModel is the character that was staggered.
• OnReleaseBreak()
   
   
   
  Fulfilled when the character leaves a staggered state.
• OnRollDice(BattleDiceBehavior)
   
   
   
  Fulfilled on rolling any combat page dice. BattleDiceBehavior is the rolled dice.
• OnRecoverHp(int)
   
   
   
  Fulfilled whenever the character recovers HP. int is the amount of HP recovered.
• OnSucceedAttack(BattleDiceBehavior)
   
   
   
  Fulfilled whenever the character lands a hit. This condition does not need to deal damage. BattleDiceBehavior is the rolled dice.
• OnTakeDamageByAttack(BattleDiceBehavior, int)
   
   
   
  Fulfilled when the character takes damage from an attack made by the rolled dice of a combat page. BattleDiceBehavior is the rolled dice and int is the amount of damage taken.
• OnTakeBreakDamageByAttack(BattleDiceBehavior, int)
   
   
   
  Fulfilled when the character takes stagger damage from an attack made by the rolled dice of a combat page. BattleDiceBehavior is the rolled dice and int is the amount of stagger damage taken.
• OnWinParrying(BattleDiceBehavior)
• OnDrawParrying(BattleDiceBehavior)
• OnLoseParrying(BattleDiceBehavior)
   
   
   
  Fulfilled when the character wins, draws or loses a clash respectively. BattleDiceBehavior is the character’s rolled dice.
• OnWaveStart()
   
   
   
  Fulfilled at the beginning of the act.
• OnRoundStart()
   
   
   
  Fulfilled at the beginning of every scene.
• OnRoundEnd()
   
   
   
  Fulfilled at the end of every scene.
• OnStartBattle()
   
   
   
  Fulfilled at the beginning of the combat phase.
• OnRollSpeedDice()
   
   
   
  Fulfilled when the speed dice have just been rolled.
• OnGiveKeywordBufByCard(BattleUnitBuf, int, BattleUnitModel)
   
   
   
  Fulfilled whenever applying a status effect to another character. Returns an int, which is the number to add onto the stack. BattleUnitBuf is the status effect being applied, int is the stack being applied, and BattleUnitModel is the target of the status effect.

 
 
 

“And when you bring it back up… it doesn’t have to be only one time. If you can do it time and time again…”

But now what do I do?

 
 
You do things. After forming the basis, now is the time to add some things to happen and that’s what this part of the guide is a reference for. Unlike conditionals, actions are broken up by the target. The target can be a character, a page, a dice, whatever, really, so long as there is something for the action to happen to. Whenever you write down an action, you always write it as {subject}.{action}({properties}); where the subject is what the action, with it’s specified properties, is happening to.
 
 

BattleUnitModel

 
 
These are characters. When a conditional is fulfilled and gives you access to one of these, it’s usually the enemy. There is also always a particular BattleUnitModel available at any given time; owner. owner refers to either the one rolling the dice for it’s ability, using the page with the acting ability, or the one with the passive equipped.
 
 
Here is a list of common actions you can apply to a character.
 
 

• TakeDamage(int, DamageType, BattleUnitModel, KeywordBuf)
   
   
   
  Inflict damage upon the character. You may leave out any property after int, but they must appear in this order. int is the amount of damage to inflict. DamageType is the type of damage to inflict; not Slash or anything, but DamageType.Attack, or DamageType.Passive. Usually, you want DamageType.Attack. BattleUnitModel is who the inflictor is, or null for no attacker. KeywordBuf is what status effect to apply with the damage, if any.
• TakeBreakDamage(int, DamageType, BattleUnitModel)
   
   
   
  Similar to above, but for stagger damage. There are more properties but I don’t precisely know what one of them means.
• RecoverHP(int)
   
   
   
  Recovers the character’s HP. Use this instead of using a negative value in TakeDamage. int is how much HP to recover.
• RecoverBreakLife(int)
   
   
   
  Recovers the character’s stagger resist. Use this instead of using a negative value in TakeBreakDamage. int is how much stagger resist to recover.

 

BattleDiceBehavior

 
 

• ApplyDiceStatBonus(DiceStatBonus)
   
   
   
  A fairly global method to manipulate a given dice. DiceStatBonus allows you to specify different fields that manipulate the dice in some way. It has to be declared in a specific way in order for it to work. This is best presented with an example:
   
   
   
   
   

  behavior.ApplyDiceStatBonus(new DiceStatBonus() 
   { 
   power = 0; // Changes the raw power of the dice.
   min = 0; // Changes the minimum roll value of the dice.
   max = 0; // Changes the maximum roll value of the dice.
   ignorePower = false; // If true, ignore the power value.
   dmgRate = 0; // Multiplies the damage inflicted by this dice.
   breakRate = 0; // Multiplies the stagger damage inflicted by this dice.
   dmg = 0; // Adds damage to the attack made by this dice.
   breakDmg = 0; // Adds stagger damage to the attack made by this dice.
   }
  );
  

 
 
 

“That ended on a trifling note. Still, it was the wise decision.”

There is still much more that can be explained, including how to get the values of certain things in battle as well as a list of status effects but by fooling around in Visual Studio, you can typically find these by putting in examples found both in the Ruina main folder as well as here. The guide is kind of incomplete but hopefully serves as an introduction enough to allow anyone interested in making custom abilities to intuit how to at this point. At the very least, you have the building blocks for basic stuff. Feel free to leave in the comments any tips or suggestions you might have.
 
 

 
 
This is all for Library Of Ruina Guide for Ruina Modding Tips – Custom Passives – Page Abilities and Dice Abilities hope you enjoy the post. If you believe we forget or we should update the post please let us know via comment, we will try our best to fix how fast is possible! Have a great day!