Skip to content

Latest commit

 

History

History
81 lines (69 loc) · 7.23 KB

CONTRIBUTING.md

File metadata and controls

81 lines (69 loc) · 7.23 KB
Raw

Contributing to ValheimPlus

How to setup your environment for V+ development

How to setup the development enviroment to compile ValheimPlus yourself.

  1. Download the BepInEx for Valheim package.
    • Extract zip contents and copy the contents inside /BepInExPack_Valheim/ and paste them in your Valheim root folder and overwrite every file when asked.
    • This package sets up your Valheim game with BepInEx configurations specifically for mod devs. Created by BepInEx.
  2. Copy over all the DLLs from Valheim/unstripped_corlib to Valheim/valheim_Data/Managed (overwrite when asked)
  3. Download the AssemblyPublicizer package.
  4. Drag and drop all assembly_*.dll files from "\Valheim\valheim_Data\Managed" folder onto "AssemblyPublicizer.exe". This will create a new folder called "/publicized_assemblies/".
  5. Define Environment Variable VALHEIM_INSTALL with path to Valheim Install Directory
    • example: setx VALHEIM_INSTALL "C:\Program Files\Steam\steamapps\common\Valheim" /M

Debugging with dnSpy

Thanks to mono and unity-mono being open source, we patched and compiled our own mono runtime and enabled actual live debugging of the game and the mod itself with dnSpy.

  1. Download dnSpy-net-win64 and extract the exe.
  2. Load all assemblies from <Valheim>\unstripped_corlib into dnSpy (just drag&drop the folder onto it).
  3. Load all assembly_* from <Valheim>\valheim_Data\Managed into dnSpy (do not load the publicized ones, they will not be loaded into the process and therefore can not be debugged).
  4. Load ValheimPlus.dll from <Valheim>\BepInEx\plugins into dnSpy.
  5. Copy .\libraries\Debug\mono-2.0-bdwgc.dll from this repo to <Valheim>\MonoBleedingEdge\EmbedRuntime and overwrite the existing file.
  6. Now go to Debug -> Start Debugging and select Unity debug engine. Select your valheim.exe as the executable and hit OK.
  7. If you did set some breakpoints, the game will halt when it hits the breakpoint in memory and dnSpy will show you the objects in memory and lets you do much more useful stuff.

V+ Conventions

C#

  1. Please add all Patched methods to the file named for the type being patched. So if we patch a class type named Humanoid, add that patch to the GameClasses/Humanoid.cs file.

  2. Patch naming convention update

    • Any new classes for patches will follow the following naming convention. Please make sure future classes are named appropriately. The objective is to simplify and avoid clashes of method patching and a potential refactor in the future.
    // File of patch == GameClass.cs file

Class structure:
[HarmonyPatch(typeof(GameClass), "MethodName")]
{modifiers} class GameClass_MethodName_Patch
{
  bool Prefix...
  void Postfix...
  // Etc...
}
    • If you are planning to do a Transpiler, replace "Patch" with "Transpiler"

  3. Please add a ///<summary> above every patched method and add comments to parts of code that is more that just a simple assignment

  4. Try to avoid using "magic strings/numbers" if possible, use class-defined consts especially if using the value more than once

  5. Always try avoid returning false in a Prefix() method if possible. This will not only skip the original method but also other Prefixs and breaks compatibility with other mods. If you need to return false please include your reasoning as a comment in the code.

Configuration .cfg

  1. Always add new configurations to the .cfg file as well as the configuration class and set the value to the default value from the game.
  2. Always add your new added configurations to the vplusconfig.json at the appropriate places with the most information you are able to fill out (for icons,FontAwesome ).
    • It is easy to forget test values in your code when you make a PR. Please double check your default values when creating a PR
    • It is recommended when testing to test value inline with your code instead of altering the values on the .cfg/class to prevent this issue. If an inline hardcoded value gets pushed, it's easier to spot this mistake than a inaccurate cfg setting.
  3. Try to find an appropriate existing configuration section before adding a new one. Generally, if your configuration changes something related to the player, for example, then add it to the [Player] section. Look at it from the perspective of a user who's looking for a specific configuration instead of the perspective of someone who's coding and looking for a class.
  4. Add any new configuration Sections ([Section]) to the bottom of the .cfg file so that we're less likely to break existing config.
  5. Check out our helpers in the /Utilities/ folder and use them where appropriate
  6. For configuration modifiers that add a modification to the base value, always use a percentage configuration and use the applyModifier() utility.
  7. For configuration modifier values make sure to add "modifier": "true" as entry stat to the vplusconfig.json.

Making a Pull Request

  1. Only make a pull request for finished work. Otherwise, if we pull the work down to test it and it doesn't work, we don't know if it's because it's unfinished or if there's an unintentional bug.
    • If you'd like a review on your work before something it's finished, send us a link to a compare via Discord or make a "Draft" PR.
  2. If you want credit, add your credit to the README.md in your pull request if the work is more than a documentation update. We will not be able to track this ourselves and rely on you to add your preferred way of being credited.
  3. After you have made a GitHub contribution, reach out to one of the V+ devs on Discord if you'd like the "GitHub contributor" role.
  4. Make sure that if your pull requests takes care of a suggestion from our website at https://valheim.plus/todo that you also remove it from the vplusSuggestions/todo.json

Pull Request labels

  1. pending merge - This work has been reviewed and accepted and will be merged after the coming release
  2. pending close - This work has not been updated for a while and will be closed if no response/update is received in 2 days
  3. needs updating - This work has received feedback and needs to be updated before being accepted
  4. merge conflicts - This pr has merge conflicts that need to be resolved
  5. question - The author of the PR needs to answer a question before the PR can move forward
  6. in discussion - We want to implement the PR but have to make more preparations and tests before we can do so.

Files

  1. valheim_plus.cfg - the file responsible for loading the configuration on game start.
  2. vplusconfig.json - the file responsible to generate the website documentation that can be found here https://valheim.plus/documentation
  3. vplusSuggestions/todo.json - the file responsible to generate the website page https://valheim.plus/todo