kongregate/display-list

Unity3D helper for for generating a list of UI elements from data

display-list's Issues

Add examples for subclassing DisplayList

Currently the package documentation recommends making a one-off subclass of DisplayList in order to give it concrete type parameters, and then using that custom subclass from your components:

// MyDisplayList.cs
public class MyDisplayList : DisplayList<MyElement, MyData> { }

// MyGameLogic.cs
public class MyGameLogic : MonoBehaviour
{
    [SerializeField]
    private MyDisplayList _displayList;

    public void Start()
    {
        var dataToDisplay = new List<MyData>() { ... };
        _displayList.Populate(dataToDisplay);
    }
}

While this approach is useful if you want to use MyDisplayList from multiple classes, it's also common to only ever have a single component that needs to use a given DisplayList subclass. In that case, the extra boilerplate can be avoided by having MyGameLogic directly subclass DisplayList:

public class MyGameLogic : DisplayList<MyElement, MyData>
{
    public void Start()
    {
        var dataToDisplay = new List<MyData>() { ... };
        Populate(dataToDisplay);
    }
}

This approach is perfectly viable, but it would be helpful to have more documentation around this case so that users are aware that it's an option.

DynamicDisplayList needs lifecycle methods

DisplayList exposes a number of virtual lifecycle methods that child classes can implement in order to customize the behavior of the list. We should add these same methods to DynamicDisplayList in order to improve feature parity between the two. These methods are: OnElementAdded, OnElementRemoved and OnPopulated.

Setup automated code style checking

The latest release of dotnet-format (v4.0.130203) seems to have added support for following the same .editorconfig rules as the roslyn complier. We already have a .editorconfig file in the repo, and I've been using it in Visual Studio to keep the code formatted consistently, so we should see if we can setup automatic checking as part of the Actions pipeline to enforce that code style stays consistent.

Support custom element instantiation in DisplayList

In some cases, users might want to use custom logic to instantiate their view elements. This is currently possible with DynamicDisplayList, since user code has full control over how the elements are instantiated. But it would be nice to also allow users to override the instantiation logic in DisplayList (and BaseDisplayList by extension).

The main use case I'm thinking of here is performing dependency injection for the created elements using a framework like Extenject. For such cases, all objects need to be instantiated through the framework in order for injection to be performed correctly.

Right now, BaseDisplayList.CreateChild() is given a reference to the prefab and optionally instantiates the prefab and will instantiate a new copy as needed. I think what we should do is add a virtual InstantiateViewElement() method that has a default implementation that simply calls Object.Instantiate(), but can be overridden by child classes in order to provide alternate instantiation logic. The other alternative is to make CreateChild() itself virtual, however that seems like it may not be ideal since CreateChild() also performs additional logic beyond just instantiating the view element.

Setup CI pipeline

We should setup a CI pipeline using GitHub Actions to build and test changes made to the package. The kongregate-web repo has an example of how to do this with multiple Unity versions.

Add a utility for creating monomorphized DisplayList subclass

Right now the recommended way of using DisplayList is to manually create a monomorphized subclass that can be directly used as a component:

public class MyCoolList : DisplayList<ViewElement, SomeData> { }

While this isn't a lot of work to do, it can be a bit tedious to manually create the file and then edit in the specific values necessary. It would be nice to have a custom script creation option that generates a new script following the expected template, similar to the built-in Create -> C# Script option.

It would be extra nice to provide some kind of prompt to allow the user to select their display element and data element types, that way they never even need to open or manually edit the generated script. This could be accomplished using reflection by searching for classes that implement IDisplayElement. We'd likely only need to make the user select a display element, since we could then deduce the data element's type from the type parameter on the IDisplayElement implementation.

Pool view elements in DynamicDisplayList

Right now, DisplayList will pool and reuse view elements when re-populating the list in order to improve performance, but DynamicDisplayList will fully instantiate a new object every time you want to create a view element. We should implement automatic object pooling for DynamicDisplayList to improve performance in the common case.

Details

Users currently use the CreateChild<V>() method (defined in BaseDisplayList) to instantiate their view element and add it to the display list's internal tracking. This method currently creates a new instance of the specified prefab every time it's called, but we could extend it to pool the created instances based on their source prefab. This would allow us to reuse existing instances when re-populating the list.

That said, we need to make sure that we do this in a way that still provides flexibility for use cases where pooling based on the prefab would either be incorrect, or not ideal:

• We should provide an escape-hatch method that creates a new view object instance without going through the object pool.
• We should provide a way for users to directly provide the instances they want to use, in order to enable them to use their own pooling implementation.
• It might make sense to allow users to provide a custom cache key per-instance, that way they can take advantage of the built-in pooling while still having control over which instance pool is used for each data element.