feature: add support for mapping view models to artboards in lists (#11524) 41002bf174

bodymovin · bodymovin · bodymovin · commit 16f3637583c1 · 2026-01-23T05:17:21.000Z
* feature: add support for mapping view models to artboards in an artboard list

Co-authored-by: hernan &lt;hernan@rive.app&gt;
diff --git a/.rive_head b/.rive_head
@@ -1 +1 @@
-e59db089ed75af8000a358c7a352d42d565b235d
+41002bf174cb409ba82c12b6803add48e969b6fb
diff --git a/dev/defs/artboard_list_map_rule.json b/dev/defs/artboard_list_map_rule.json
@@ -0,0 +1,32 @@
+{
+  "name": "ArtboardListMapRule",
+  "key": {
+    "int": 648,
+    "string": "artboardlistmaprule"
+  },
+  "extends": "component.json",
+  "properties": {
+    "artboardId": {
+      "type": "Id",
+      "typeRuntime": "uint",
+      "initialValue": "Core.missingId",
+      "initialValueRuntime": "-1",
+      "key": {
+        "int": 934,
+        "string": "artboardid"
+      },
+      "description": "Artboard id to map"
+    },
+    "viewModelId": {
+      "type": "Id",
+      "typeRuntime": "uint",
+      "initialValue": "Core.missingId",
+      "initialValueRuntime": "-1",
+      "key": {
+        "int": 935,
+        "string": "viewmodelid"
+      },
+      "description": "iew model id to map"
+    }
+  }
+}
diff --git a/include/rive/artboard_component_list.hpp b/include/rive/artboard_component_list.hpp
@@ -20,6 +20,7 @@ namespace rive
 {
 class LayoutComponent;
 class ScrollConstraint;
+class ArtboardListMapRule;
 
 class ArtboardComponentList : public ArtboardComponentListBase,
                               public ArtboardHost,
@@ -115,6 +116,7 @@ class ArtboardComponentList : public ArtboardComponentListBase,
     LayoutComponent* layoutParent();
     const Mat2D& listTransform() override;
     void listItemTransforms(std::vector<Mat2D*>& transforms) override;
+    void addMapRule(ArtboardListMapRule*);
 
 private:
     void updateArtboardsWorldTransform();
@@ -159,6 +161,7 @@ class ArtboardComponentList : public ArtboardComponentListBase,
     int m_visibleEndIndex = -1;
     std::unordered_map<ArtboardInstance*, ArtboardComponentListOverride*>
         m_artboardOverridesMap;
+    std::unordered_map<int, int> m_artboardMapRules;
     void attachArtboardOverride(ArtboardInstance*,
                                 rcp<ViewModelInstanceListItem>);
     void clearArtboardOverride(ArtboardInstance*);
diff --git a/include/rive/artboard_list_map_rule.hpp b/include/rive/artboard_list_map_rule.hpp
@@ -0,0 +1,14 @@
+#ifndef _RIVE_ARTBOARD_LIST_MAP_RULE_HPP_
+#define _RIVE_ARTBOARD_LIST_MAP_RULE_HPP_
+#include "rive/generated/artboard_list_map_rule_base.hpp"
+#include <stdio.h>
+namespace rive
+{
+class ArtboardListMapRule : public ArtboardListMapRuleBase
+{
+public:
+    StatusCode onAddedDirty(CoreContext* context) override;
+};
+} // namespace rive
+
+#endif
diff --git a/include/rive/generated/artboard_list_map_rule_base.hpp b/include/rive/generated/artboard_list_map_rule_base.hpp
@@ -0,0 +1,89 @@
+#ifndef _RIVE_ARTBOARD_LIST_MAP_RULE_BASE_HPP_
+#define _RIVE_ARTBOARD_LIST_MAP_RULE_BASE_HPP_
+#include "rive/component.hpp"
+#include "rive/core/field_types/core_uint_type.hpp"
+namespace rive
+{
+class ArtboardListMapRuleBase : public Component
+{
+protected:
+    typedef Component Super;
+
+public:
+    static const uint16_t typeKey = 648;
+
+    /// Helper to quickly determine if a core object extends another without
+    /// RTTI at runtime.
+    bool isTypeOf(uint16_t typeKey) const override
+    {
+        switch (typeKey)
+        {
+            case ArtboardListMapRuleBase::typeKey:
+            case ComponentBase::typeKey:
+                return true;
+            default:
+                return false;
+        }
+    }
+
+    uint16_t coreType() const override { return typeKey; }
+
+    static const uint16_t artboardIdPropertyKey = 934;
+    static const uint16_t viewModelIdPropertyKey = 935;
+
+protected:
+    uint32_t m_ArtboardId = -1;
+    uint32_t m_ViewModelId = -1;
+
+public:
+    inline uint32_t artboardId() const { return m_ArtboardId; }
+    void artboardId(uint32_t value)
+    {
+        if (m_ArtboardId == value)
+        {
+            return;
+        }
+        m_ArtboardId = value;
+        artboardIdChanged();
+    }
+
+    inline uint32_t viewModelId() const { return m_ViewModelId; }
+    void viewModelId(uint32_t value)
+    {
+        if (m_ViewModelId == value)
+        {
+            return;
+        }
+        m_ViewModelId = value;
+        viewModelIdChanged();
+    }
+
+    Core* clone() const override;
+    void copy(const ArtboardListMapRuleBase& object)
+    {
+        m_ArtboardId = object.m_ArtboardId;
+        m_ViewModelId = object.m_ViewModelId;
+        Component::copy(object);
+    }
+
+    bool deserialize(uint16_t propertyKey, BinaryReader& reader) override
+    {
+        switch (propertyKey)
+        {
+            case artboardIdPropertyKey:
+                m_ArtboardId = CoreUintType::deserialize(reader);
+                return true;
+            case viewModelIdPropertyKey:
+                m_ViewModelId = CoreUintType::deserialize(reader);
+                return true;
+        }
+        return Component::deserialize(propertyKey, reader);
+    }
+
+protected:
+    virtual void artboardIdChanged() {}
+    virtual void viewModelIdChanged() {}
+};
+} // namespace rive
+
+#endif
diff --git a/include/rive/generated/core_registry.hpp b/include/rive/generated/core_registry.hpp
@@ -90,6 +90,7 @@
 #include "rive/animation/transition_viewmodel_condition.hpp"
 #include "rive/artboard.hpp"
 #include "rive/artboard_component_list.hpp"
+#include "rive/artboard_list_map_rule.hpp"
 #include "rive/assets/asset.hpp"
 #include "rive/assets/audio_asset.hpp"
 #include "rive/assets/drawable_asset.hpp"
@@ -805,6 +806,8 @@ class CoreRegistry
                 return new Text();
             case TextValueRunBase::typeKey:
                 return new TextValueRun();
+            case ArtboardListMapRuleBase::typeKey:
+                return new ArtboardListMapRule();
             case CustomPropertyEnumBase::typeKey:
                 return new CustomPropertyEnum();
             case FolderBase::typeKey:
@@ -1530,6 +1533,12 @@ class CoreRegistry
             case TextValueRunBase::styleIdPropertyKey:
                 object->as<TextValueRunBase>()->styleId(value);
                 break;
+            case ArtboardListMapRuleBase::artboardIdPropertyKey:
+                object->as<ArtboardListMapRuleBase>()->artboardId(value);
+                break;
+            case ArtboardListMapRuleBase::viewModelIdPropertyKey:
+                object->as<ArtboardListMapRuleBase>()->viewModelId(value);
+                break;
             case CustomPropertyEnumBase::propertyValuePropertyKey:
                 object->as<CustomPropertyEnumBase>()->propertyValue(value);
                 break;
@@ -2982,6 +2991,10 @@ class CoreRegistry
                 return object->as<TextBase>()->textRunListSource();
             case TextValueRunBase::styleIdPropertyKey:
                 return object->as<TextValueRunBase>()->styleId();
+            case ArtboardListMapRuleBase::artboardIdPropertyKey:
+                return object->as<ArtboardListMapRuleBase>()->artboardId();
+            case ArtboardListMapRuleBase::viewModelIdPropertyKey:
+                return object->as<ArtboardListMapRuleBase>()->viewModelId();
             case CustomPropertyEnumBase::propertyValuePropertyKey:
                 return object->as<CustomPropertyEnumBase>()->propertyValue();
             case CustomPropertyEnumBase::enumIdPropertyKey:
@@ -3857,6 +3870,8 @@ class CoreRegistry
             case TextBase::verticalAlignValuePropertyKey:
             case TextBase::textRunListSourcePropertyKey:
             case TextValueRunBase::styleIdPropertyKey:
+            case ArtboardListMapRuleBase::artboardIdPropertyKey:
+            case ArtboardListMapRuleBase::viewModelIdPropertyKey:
             case CustomPropertyEnumBase::propertyValuePropertyKey:
             case CustomPropertyEnumBase::enumIdPropertyKey:
             case FileAssetBase::assetIdPropertyKey:
@@ -4619,6 +4634,10 @@ class CoreRegistry
                 return object->is<TextBase>();
             case TextValueRunBase::styleIdPropertyKey:
                 return object->is<TextValueRunBase>();
+            case ArtboardListMapRuleBase::artboardIdPropertyKey:
+                return object->is<ArtboardListMapRuleBase>();
+            case ArtboardListMapRuleBase::viewModelIdPropertyKey:
+                return object->is<ArtboardListMapRuleBase>();
             case CustomPropertyEnumBase::propertyValuePropertyKey:
                 return object->is<CustomPropertyEnumBase>();
             case CustomPropertyEnumBase::enumIdPropertyKey:
diff --git a/src/artboard_component_list.cpp b/src/artboard_component_list.cpp
@@ -8,6 +8,7 @@
 #include "rive/viewmodel/viewmodel_instance_symbol_list_index.hpp"
 #include "rive/world_transform_component.hpp"
 #include "rive/layout/layout_data.hpp"
+#include "rive/artboard_list_map_rule.hpp"
 
 using namespace rive;
 
@@ -137,17 +138,34 @@ Artboard* ArtboardComponentList::findArtboard(
     {
         return nullptr;
     }
-    auto artboard = m_artboardsMap.find(viewModelInstance->viewModelId());
+    auto viewModelId = viewModelInstance->viewModelId();
+    // Find artboard in the cached mappings
+    auto artboard = m_artboardsMap.find(viewModelId);
     if (artboard != m_artboardsMap.end())
     {
         return artboard->second;
     }
     auto artboards = m_file->artboards();
+    // Check if there is a special rule that maps the view model to a specific
+    // artboard
+    auto listRule = m_artboardMapRules.find(viewModelId);
+    if (listRule != m_artboardMapRules.end())
+    {
+        auto artboardIndex = listRule->second;
+        if (artboardIndex < artboards.size())
+        {
+            auto artboard = artboards[artboardIndex];
+            m_artboardsMap[viewModelId] = artboard;
+            return artboard;
+        }
+    }
+
+    // Search for the first artboard that is bound to this view model
     for (auto& artboard : artboards)
     {
-        if (artboard->viewModelId() == viewModelInstance->viewModelId())
+        if (artboard->viewModelId() == viewModelId)
         {
-            m_artboardsMap[viewModelInstance->viewModelId()] = artboard;
+            m_artboardsMap[viewModelId] = artboard;
             return artboard;
         }
     }
@@ -1081,4 +1099,9 @@ void ArtboardComponentList::listItemTransforms(std::vector<Mat2D*>& transforms)
             transforms.push_back(&m_artboardTransforms[artboard]);
         }
     }
+}
+
+void ArtboardComponentList::addMapRule(ArtboardListMapRule* rule)
+{
+    m_artboardMapRules[rule->viewModelId()] = rule->artboardId();
 }
diff --git a/src/artboard_list_map_rule.cpp b/src/artboard_list_map_rule.cpp
@@ -0,0 +1,21 @@
+#include "rive/component.hpp"
+#include "rive/file.hpp"
+#include "rive/artboard_list_map_rule.hpp"
+#include "rive/artboard_component_list.hpp"
+
+using namespace rive;
+
+StatusCode ArtboardListMapRule::onAddedDirty(CoreContext* context)
+{
+    StatusCode code = Super::onAddedDirty(context);
+    if (code != StatusCode::Ok)
+    {
+        return code;
+    }
+    if (!parent()->is<ArtboardComponentList>())
+    {
+        return StatusCode::MissingObject;
+    }
+    parent()->as<ArtboardComponentList>()->addMapRule(this);
+    return StatusCode::Ok;
+}
diff --git a/src/generated/artboard_list_map_rule_base.cpp b/src/generated/artboard_list_map_rule_base.cpp
@@ -0,0 +1,11 @@
+#include "rive/generated/artboard_list_map_rule_base.hpp"
+#include "rive/artboard_list_map_rule.hpp"
+
+using namespace rive;
+
+Core* ArtboardListMapRuleBase::clone() const
+{
+    auto cloned = new ArtboardListMapRule();
+    cloned->copy(*this);
+    return cloned;
+}
diff --git a/tests/unit_tests/assets/artboard_list_map_rules.riv b/tests/unit_tests/assets/artboard_list_map_rules.riv
diff --git a/tests/unit_tests/runtime/component_list_test.cpp b/tests/unit_tests/runtime/component_list_test.cpp
@@ -955,3 +955,26 @@ TEST_CASE("Virtualized list with nested data bound artboards",
 
     CHECK(silver.matches("virtualized_artboard_databound_children"));
 }
+
+TEST_CASE("Artboard list map rules", "[component_list]")
+{
+    rive::SerializingFactory silver;
+    auto file = ReadRiveFile("assets/artboard_list_map_rules.riv", &silver);
+
+    auto artboard = file->artboardDefault();
+    silver.frameSize(artboard->width(), artboard->height());
+
+    auto stateMachine = artboard->stateMachineAt(0);
+    int viewModelId = artboard.get()->viewModelId();
+
+    auto vmi = viewModelId == -1
+                   ? file->createViewModelInstance(artboard.get())
+                   : file->createViewModelInstance(viewModelId, 0);
+
+    stateMachine->bindViewModelInstance(vmi);
+    auto renderer = silver.makeRenderer();
+    stateMachine->advanceAndApply(0.016f);
+    artboard->draw(renderer.get());
+
+    CHECK(silver.matches("artboard_list_map_rules"));
+}
diff --git a/tests/unit_tests/silvers/artboard_list_map_rules.sriv b/tests/unit_tests/silvers/artboard_list_map_rules.sriv

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-e59db089ed75af8000a358c7a352d42d565b235d`
	`1`	`+41002bf174cb409ba82c12b6803add48e969b6fb`
Original file line number	Diff line number	Diff line change
`@@ -8,6 +8,7 @@`
`8`	`8`	`#include "rive/viewmodel/viewmodel_instance_symbol_list_index.hpp"`
`9`	`9`	`#include "rive/world_transform_component.hpp"`
`10`	`10`	`#include "rive/layout/layout_data.hpp"`
	`11`	`+#include "rive/artboard_list_map_rule.hpp"`
`11`	`12`
`12`	`13`	`using namespace rive;`
`13`	`14`
`@@ -137,17 +138,34 @@ Artboard* ArtboardComponentList::findArtboard(`
`137`	`138`	`{`
`138`	`139`	`return nullptr;`
`139`	`140`	`}`
`140`		`- auto artboard = m_artboardsMap.find(viewModelInstance->viewModelId());`
	`141`	`+ auto viewModelId = viewModelInstance->viewModelId();`
	`142`	`+ // Find artboard in the cached mappings`
	`143`	`+ auto artboard = m_artboardsMap.find(viewModelId);`
`141`	`144`	`if (artboard != m_artboardsMap.end())`
`142`	`145`	`{`
`143`	`146`	`return artboard->second;`
`144`	`147`	`}`
`145`	`148`	`auto artboards = m_file->artboards();`
	`149`	`+ // Check if there is a special rule that maps the view model to a specific`
	`150`	`+ // artboard`
	`151`	`+ auto listRule = m_artboardMapRules.find(viewModelId);`
	`152`	`+ if (listRule != m_artboardMapRules.end())`
	`153`	`+ {`
	`154`	`+ auto artboardIndex = listRule->second;`
	`155`	`+ if (artboardIndex < artboards.size())`
	`156`	`+ {`
	`157`	`+ auto artboard = artboards[artboardIndex];`
	`158`	`+ m_artboardsMap[viewModelId] = artboard;`
	`159`	`+ return artboard;`
	`160`	`+ }`
	`161`	`+ }`
	`162`	`+`
	`163`	`+ // Search for the first artboard that is bound to this view model`
`146`	`164`	`for (auto& artboard : artboards)`
`147`	`165`	`{`
`148`		`- if (artboard->viewModelId() == viewModelInstance->viewModelId())`
	`166`	`+ if (artboard->viewModelId() == viewModelId)`
`149`	`167`	`{`
`150`		`- m_artboardsMap[viewModelInstance->viewModelId()] = artboard;`
	`168`	`+ m_artboardsMap[viewModelId] = artboard;`
`151`	`169`	`return artboard;`
`152`	`170`	`}`
`153`	`171`	`}`
`@@ -1081,4 +1099,9 @@ void ArtboardComponentList::listItemTransforms(std::vector<Mat2D*>& transforms)`
`1081`	`1099`	`transforms.push_back(&m_artboardTransforms[artboard]);`
`1082`	`1100`	`}`
`1083`	`1101`	`}`
	`1102`	`+}`
	`1103`	`+`
	`1104`	`+void ArtboardComponentList::addMapRule(ArtboardListMapRule* rule)`
	`1105`	`+{`
	`1106`	`+ m_artboardMapRules[rule->viewModelId()] = rule->artboardId();`
`1084`	`1107`	`}`