November 15, 2021

Evergine package system

Reusability is a widespread concept in software development and we, as developers, are always thinking in a way to isolate parts of our code to create libraries, code snippets, or assets that could be consumed from different projects. In .NET world, it’s very common to create NuGet packages to share libraries.

Evergine itself uses NuGet format to be distributed, and thanks to that we provide many built-in behaviors, components, or services. But it’s not that easy if you want to share assets like textures, effects, or materials from the Content folder of an Evergine project. To solve this problem, we have been working in a new package system, that will let you distribute assets that could be reused in many projects.

Add an existing package

When a package is added, all its assets, source code, and NuGet dependencies will be added for you.

Right now, it’s not possible to add a package using Evergine Studio user interface, you need to do it manually. Just open your Evergine project file (.weproj file) with your favorite text editor and update Packages section with those packages that you want to include.

Just check the list of official package IDs to add new entries.

For example:

After doing this, opening your project with Evergine Studio should add a Dependencies node in your Project Explorer. That node will contain all referenced packages. You can expand package nodes to see its contents.

As part of a package, assets are marked as read-only. If you need to modify any of them, it’s possible: a copy of the asset will be created in your project. This local copy overwrites original package asset for your current project.

Alternatively, you can also reference a package by local path. This is useful if you are including your own made packages. In this case, the syntax will be:

Please, notice that referencing a local package does not mark package assets as read-only, and if you modify them, you are changing your local package files!

Create your own package

To create your own Evergine package you need to create a separated project with assets and source code files that you want to include. To illustrate this we are going to create a fictional package called DummyPackage with a single texture and a single component.

After creating an empty project, we need to create a package definition file. It should have a .wespec as extension name and there you can specify:

  • Owners: Name of package owners.
  • Authors: Name of package authors.
  • Description: A description of package contents.
  • Tags: A list of tags to categorize the package.
  • Nugets: A list of dependencies provided via NuGet packages.

Package definition file should be placed at the same level than project file.

All assets like textures, materials, effects, etc. should be placed under a folder named Content, and source code files should be placed under a folder named Source.

Also, you need to include Evergine.Packages.Targets NuGet package to your project to execute packaging process once building the project.

Once you have all this set up, just build your project. In your bin/Debug or bin/Release folder, you will find generated wepkg file.

If you want to reference this package as a local package, just remember to add appropriate entry in your weproj file.

To see a working sample, just take a look to any of our package repositories, like MixedRealityToolkit repository.

In conclusion, this new package system has born to make life easier for us, the developers. In future versions, we are planning to add a full Evergine Studio experience to manage those packages, and make it easier to add and remove packages.

Sergio Escalada
Sergio Escalada
Plain Concepts Research