User Story
As a plugin developer I want to specify piece categories, and add custom categories so that my piece additions are easy to find and use.

Envisioned Solution
When specifying a PieceConfig, I want to be able to set the category for a piece to a vanilla category, or a custom category.
The PieceManager should expose categories for adding additional custom tabs to specific piecetables.

Port over code from this branch: jotunnlib/jotunnlib@14b2ea6
to allow for adding recipes (item conversions) to cooking recipes

I'd like to check if a custom command has already been loaded, but the list of loaded console commands is marked as internal. Is this something that can/should be changed? I'm not too experienced with the library so I'm not sure if it's possible or if it even makes sense.

User Story
As a lazy user I want to serialise objects and fields so that I don't have to acquire a json dependency for myself.

Envisioned Solution
Make simpleJSON public instead of internal

Additional context
requested by Juha686#9097

Add an API for mod configs. Sync & GUI code can be transferred from https://github.com/sirskunkalot/Veilheim

Currently, the server's required mod list and the clients current mod list are presented to the user upon a failed connection.

We can make this more concise by simply listing the offending/required packages which are missing, or mis-versioned.

Things to do before making JotunnLib public on nuget.org:

• check/fix nuget meta informations
• nuget deploy (github action)
• nuget auto versioning (github actions at main merge?)

For the meta informations: Core team please check info and report changes or missing entries.
Nuget deploy: Need to get API Key, add deploy to github workflow
Nuget auto versioning on production workflow: Implementation needed, GitVersionTask maybe would help here

A NetworkCompatibilityModule for plugin developers to "enforce" synchronisation between client's mods/versions, and potentially configs.

See: https://github.com/risk-of-thunder/R2API/blob/master/R2API/Utils/NetworkCompatibility.cs

• Must ensure plugins can request clients to have a certain dependency
• Must ensure plugins can request clients to have a certain version of that dependency
• Must ensure plugins can be permissive with versioning
• Must ensure synchronisation of specific configurations / bep whole configurations
• Does NOT attempt to act as an anti-cheat.
• Clients failing to meet conditions must be notified of the offending/lacking dependencies if/when connection is refused.

Potentially utilise/suggest https://github.com/BepInEx/BepInEx.ConfigurationManager for UI frontend for configs

showcase the .OrNull GO extension in examples, and update the respective documentation.

see: Valheim-Modding/ExampleMod#1

A lot of stuff he we should consider including in a project template.

JotunnLib adds a GameObject to the DDOL scene. Prefabs and mocked Prefabs are on the same GameObject now. Separate them.

We should add a section to the documentation, with code examples, that explains how to transition existing mods from ValheimLib and JotunnLib to the new combined Jotunn lib.

Requirements:

• Adding JVL to existing project
• Transition guide for JotunnLib
• Transition guide for ValheimLib

Some links in the wiki still link to https://github.com/jotunnlib/jotunnlib/blob/main/

As mentioned: #32 (comment) we would need to remove this inheritance, and instead use interfaces in order to implement unit testing. Similarly if we really want to go down this route we should look into the Dependency Injection design pattern and integrate it into all managers so that we can pass our collections as dependencies via constructor, param, or method.

This would mean rewriting how we invoke our managers, however it should allow us to be more consistent in code quality.

As more mods need custom key bindings it would be nice to have a common approach to coordinating / de-conflicting bindings. There are a few different ways I could see this working ranging in technical complexity from agreed upon standards although way to common code library for managing key bindings. While some of the less technical approaches may not need Jotunn library support for them it seems this wiki would still be a good place to document them.

I'm throwing some possible options below, likely some combination of them will end up making sense. I'm sure there may be other solutions that would work even better.

Option 1:
Mods standardize on using a ModKeyBinding section in BepinEx.Configuration. This would allow the user to easily see all of the custom key bindings they need to setup.

Option 2:
For common custom button bindings Jotunn sets up the key binding for them. An example of this would be several mods may want a Use2 binding. Jotunn's config could define the Use2 key binding so that mods wouldn't have to manage the configuration themselves. For something like Use2 we could also have an agreed upon interface where a method Interact2 gets called on the object being used.

Option 3:
Jotunn provides mechanism for mods to register key bindings needed and they get added to the actual Valheim configuration screen as opposed to just a BepinEx configuration file.

The event based Register/Load schema is still present in some managers. Remove them.

RaiseSkill throws NRE when given a custom skill, as such:

        void addSkills()
        {
            // Test adding a skill with a texture
            Sprite testSkillSprite = Sprite.Create(testTex, new Rect(0f, 0f, testTex.width, testTex.height), Vector2.zero);
            //TestSkillType = SkillManager.Instance.AddSkill("com.jotunnlib.JotunnModExample.testskill", "TestingSkill", "A nice testing skill!", 1f, testSkillSprite);
            TestSkillType = SkillManager.Instance.AddSkill(new SkillConfig { Identifier = "com.jotunnlib.JotunnModExample.testskill",
                Name = "TestingSkill",
                Description = "A nice testing skill!",
                Icon = testSkillSprite,
                IncreaseStep = 1f
            }, true);
            Logger.LogDebug(TestSkillType);
            //if(!TestSkillType) Logger.
        }

private void Update()
        {
            if (Input.GetKeyDown(KeyCode.F8))
            { // Set a breakpoint here to break on F6 key press
                Player.m_localPlayer.RaiseSkill(TestSkillType, 1);
            }
        }

The first stack trace occurs on hitting F8. The second occurs upon opening the skills window.

[Error  : Unity Log] NullReferenceException: Object reference not set to an instance of an object
Stack trace:
Skills+Skill.Raise (System.Single factor) (at <6fd2223d69c147d18c77057ce0dedd7b>:0)
Skills.RaiseSkill (Skills+SkillType skillType, System.Single factor) (at <6fd2223d69c147d18c77057ce0dedd7b>:0)
Player.RaiseSkill (Skills+SkillType skill, System.Single value) (at <6fd2223d69c147d18c77057ce0dedd7b>:0)
JotunnModExample.JotunnModExample.Update ()

[Info   : Unity Log] 04/11/2021 23:21:19: Setting selected recipe 0

[Info   : Unity Log] 04/11/2021 23:21:19: UI Group status changed root = True

[Info   : Unity Log] 04/11/2021 23:21:19: UI Group status changed Player = True

[Error  : Unity Log] NullReferenceException: Object reference not set to an instance of an object
Stack trace:
SkillsDialog.Setup (Player player) (at <6fd2223d69c147d18c77057ce0dedd7b>:0)
InventoryGui.OnOpenSkills () (at <6fd2223d69c147d18c77057ce0dedd7b>:0)
UnityEngine.Events.InvokableCall.Invoke () (at <51725b129ecd4967a9a213c1ae65b295>:0)
UnityEngine.Events.UnityEvent.Invoke () (at <51725b129ecd4967a9a213c1ae65b295>:0)
UnityEngine.UI.Button.Press () (at <5abdc278a459476dabe36f8ad65ea091>:0)
UnityEngine.UI.Button.OnPointerClick (UnityEngine.EventSystems.PointerEventData eventData) (at <5abdc278a459476dabe36f8ad65ea091>:0)
UnityEngine.EventSystems.ExecuteEvents.Execute (UnityEngine.EventSystems.IPointerClickHandler handler, UnityEngine.EventSystems.BaseEventData eventData) (at <5abdc278a459476dabe36f8ad65ea091>:0)
UnityEngine.EventSystems.ExecuteEvents.Execute[T] (UnityEngine.GameObject target, UnityEngine.EventSystems.BaseEventData eventData, UnityEngine.EventSystems.ExecuteEvents+EventFunction`1[T1] functor) (at <5abdc278a459476dabe36f8ad65ea091>:0)
UnityEngine.EventSystems.EventSystem:Update()

When raise skill is performed, the sword skill is set to level 100:

• Ensure all xref's are resolved
• Visual inspection of all tutorial pages
• Ensure menu's contain all relevant links

Ensure all TODO's are removed:

• Unity.md requires death's example converted to JVL ?
• overview.md managers descr.

LocalizationManager still uses the Register and Load events.

Although the VL implementation is feature complete, it is a naiive merge for these two libs, and now requires tighter integration with the Manager abstractions.

User Story

As a Mod developer I want to be able to refactor my code related to prefabs so that prefabs have unchanged identity unless I explicitly decided them to do so.

As a Player I want to have my custom items/pieces persist in world even after updating mod so that I'm able to take latest version of mods without losing progress in my saved world.

Envisioned Solution

Using InstantiateClone (or similar method) shouldn't alter name provided by developer in a way that prevents developer from any further changes around calling this method. Like it currently does in ValheimLib

Additional context

I've developed a mod that adds custom piece ‘SignedChest’. It is registered with following code:

GameObject signedLocker = assetBundle.LoadAsset<GameObject>("Assets/Pieces/SignedChest.prefab");
siqnedLocker.FixReferences();
GameObject cloned = signedLocker.InstantiateClone("SignedChest");

Which is called from namespace ChestReloaded.Pieces from class SignedLocker from method AddSignedChestPiece which ends up with the name of instance equal to SignedChest_ChestReloaded_SigqnedLocker_AddSignedChestPiece(Clone).
After small refactoring where this code was moved to method AddPrefab loading world with placed pieces from previous mod version causes them to be destroyed as invalid prefabs, because now mod registers prefab with name SignedChest_ChestReloaded_SigqnedLocker_AddPrefab(Clone) which differs from name of prefab in savegame.

It might be fixed with following line in mod code:

cloned.name = "SignedChest_ChestReloaded_SigqnedLocker_AddSignedChestPiece(Clone)";

But it seems like such problem shouldn't appear in first place.

Actions previously depended on env vars, which are no longer used and need to be updated.

Perhaps it would be worth it to add some more precise controls for the NetworkCompatibility.VersionStrictness enum. It may be useful to allow something along the lines of:

• Versions do not matter
• Everyone needs same major version, minor.patch does not matter
• Everyone needs same major.minor version, patch does not matter
• Everyone needs same mod version for major.minor.patch

KeyHints are the "help" texts for the button config in the right corner. Basic implementation with ButtonConfigs for Keyboard is there, need to include Joystick hints as well.

Currently, only modded items are saved separately from player data. Would it be worth it to attempt to save modded player skills separately as well?

Added try-catch to entity instantiation/fix (https://github.com/Valheim-Modding/Jotunn/blob/dev/JotunnLib/Managers/ItemManager.cs#L106 for example). To counter following exceptions, remove failed items again from the manager.

Use ObjectManager to facilitate integration into Jotunn

The EventManager's use is questionable using MonoHook. Delete it.

InputManager still uses the Register and Load events.

During documentation, there was an inconsistency which has jumped out at me, and we must resolve before we release to the public as this will be a "now or never" change which will affect all documentation, examples, and dependant plugins going forward.

I will preface this issue by detailing the vanilla game's implementation for two similar object interfaces.

First, we have two individual component systems within valheim, that live in the ObjectDB. We have the m_recipes collection, and the m_items collection. Recipe is comprised of two notable attributes: public ItemDrop m_item;, and public Piece.Requirement[] m_resources = new Piece.Requirement[0];. Meanwhile, the m_items collection is of generic GameObjects, which may have an ItemDrop component, the same ItemDrop which can be referenced from a recipe.

Secondly, we have Pieces, that short of their piecetables do not have a objectDB style collection. Pieces, have a subclass named Requirement, which is a basic structure that defines an public ItemDrop m_resItem; and a quantity as an ingredient.

At this point, its clear to see some similarities in these implementations. Now lets look forward at how we interface with these libraries within our JVL abstractions:

Item

private void CreateBlueprintRune()
{
    // Create and add a custom item
    // CustomItem can be instantiated with an AssetBundle and will load the prefab from there
    CustomItem rune = new CustomItem(BlueprintRuneBundle, "BlueprintRune", false);
    ItemManager.Instance.AddItem(rune);

    // Create and add a recipe for the custom item
    CustomRecipe runeRecipe = new CustomRecipe(new RecipeConfig()
    {
        Item = "BlueprintRune",
        Amount = 1,
        Requirements = new PieceRequirementConfig[]
        {
            new PieceRequirementConfig {Item = "Stone", Amount = 1}
        }
    });
    ItemManager.Instance.AddRecipe(runeRecipe);
}

In the above, we create a CustomItem, and a CustomRecipe which can take a RecipeConfig as a parameter, that also requires a PieceRequirementConfig property to define its ingredient list.

Piece

private void CreateRunePieces()
{
    // Create and add custom pieces
    GameObject makebp_prefab = BlueprintRuneBundle.LoadAsset<GameObject>("make_blueprint");
    CustomPiece makebp = new CustomPiece(makebp_prefab, new PieceConfig
    {
        PieceTable = "_BlueprintPieceTable",
        AllowedInDungeons = false
    });
    PieceManager.Instance.AddPiece(makebp);
    GameObject placebp_prefab = BlueprintRuneBundle.LoadAsset<GameObject>("piece_blueprint");
    CustomPiece placebp = new CustomPiece(placebp_prefab, new PieceConfig
    {
        PieceTable = "_BlueprintPieceTable",
        AllowedInDungeons = true,
        Requirements = new PieceRequirementConfig[]
        {
            new PieceRequirementConfig {Item = "Wood", Amount = 2}
        }
    });
    blueprintRuneLocalizations();
    PieceManager.Instance.AddPiece(placebp);
}

Inconsistency

In the above, we create a CustomPiece, which takes PieceConfig as a parameter, that also requires a PieceRequirementConfig property to define its ingredient list.

If we compare this to the item example:

In the above, we create a CustomItem, and a CustomRecipe which can take a RecipeConfig as a parameter, that also requires a PieceRequirementConfig property to define its ingredient list.

The problem:

The problem here is inconsistency. We are obfuscating native implementations via our abstractions using inconsistent naming schemas to accomplish the same operations, not to mention potentially having some redundant nesting of tightly coupled objects/types when we could just abstract them away with parameters, but that's a problem for another time.

Bellow, I will note our equivalent implementation names, and what i suggest they should become

We can see that if we were to apply consistent naming schema, then the CustomItem should have an ItemConfig, not a CustomRecipe as a component parameter.

Furthermore, PieceRequirementConfig is a misnaming within the vanilla libraries, and just further adds to the confusing as now items have piece requirements, which makes 0 sense at all either.

We are better than this, there is no need to make this mistake and we can correct it before we release. I suggest that we do as such.

Needs some lib hooks for vanilla methods. See https://github.com/Valheim-Modding/Wiki/wiki/Item-Variants

Various configs should be deserializable from JSON, such as:

• SkillConfig
• RecipeConfig

All features and interfaces must be documented. A template project should also be provided to allow ease of use for new developers.

• Refine documentation for deployment
• example mod (In Progress, comprised of the following:)
• getting started / ModStub & Config
• importing assets
• custom items
• custom pieces & piece tables
• custom status effects
• custom skills
• using mock references inside assets
• VL Asset Creation Walkthrough
• adding localisations
• GUIManager

Utilities:

• Configs
• NetworkCompatibility
• AssetUtils
• BoneReorder
• Input
• Commands

Doc's such as debug information, unity setup etc are better directed toward the modding wiki than duplicated here. If we have any JVL specific implementations such as J/VLmock_ prefixing for asset creation then include these, but only link to generic information which is tangential to our project.

We're currently not keeping track of changes at all in this repo. We should create some form of changelog markdown file documenting what we've done up to the initial release, and what feature will be available upon release.

Additionally, we should clean up (or honestly, probably could even entirely remove) the "features & roadmap" section from the README.

• Features
• Roadmap
• Thunderstore README.md
• Nexus page ?????
• Begin curated changelog via a featurelist

• ModExample
• ModStub

Look into how we can generate the MMHOOK publicized assemblies at runtime, when Jotunn is loaded. This way, we won't need to ship the DLLs with the library, and they'll always be up-to-date for users. Additionally, it should be less cumbersome for users to deal with installing our library if there's less DLLs for them to fetch,

(https://github.com/GoldenJude GoldenJude
#8965) said he was working on creating an implementation to allow easy tweaks to bone attach points, and would potentially be willing to PR into JVL.

Not sure if this is an issue or not yet, but wanted to repost an issue raised on one of the PRs on the JotunnLib repo:
jotunnlib/jotunnlib#21

It appears that some strings can have a negative hash code, which then results in a negative SkillConfg UID (used for Skill.SkillType).

EDIT: It appears it throws errors on negative UID. With the errors fixed, negative UIDs seem to work just fine :)

• Remove restrictions on requiring tokens to start with $ char
• Disallow users from using any characters from Localization.m_endChars in their tokens, as they will not be usable

#31 breaks the TestMod completely. We need to rebuild it with the new concepts and see along the way what should be next / changed in the merger in general. #31 shuold be the base of that, though.

ButtonConfig instances are only generated on the fly. For KeyHints they should be created outside the InputManager and the manager needs an Add(ButtonConfig) method.

Currently, there is a mix of various naming conventions being used. Naming conventions across all files should be changed to use:

• lowerCamelCase for private/local member variables and methods
• UpperCamelCase for classes, and public/internal methods and variables
• Remove any uses for Hungarian notation, such as the m_ member variable prefix used by Valheim