# iyouthy/godot-recycler-view architecture

> Architecture diagram of the GitHub repository iyouthy/godot-recycler-view, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/iyouthy/godot-recycler-view
- Repository: https://github.com/iyouthy/godot-recycler-view

## Overview

godot-recycler-view is a Godot 4 GDExtension providing Android-style virtualized lists. A GDScript client configures a RecyclerView with an Adapter and LayoutManager; visible items are obtained and bound through the recycling system, laid out, and displayed in the Godot viewport. Data updates can use incremental notifications or ListAdapter diffing. The README documents animation, touch, snapping, decoration, scroll, and multiple layout capabilities. Wiring for these documented features is represented at subsystem level because their implementations were not sampled.

Main entry points: [`src/recycler_view.cpp`](https://github.com/iyouthy/godot-recycler-view/blob/main/src/recycler_view.cpp) (RecyclerView), [`src/recycler.cpp`](https://github.com/iyouthy/godot-recycler-view/blob/main/src/recycler.cpp) (Recycler), [`src/adapter.cpp`](https://github.com/iyouthy/godot-recycler-view/blob/main/src/adapter.cpp) (Adapter), [`src/diff_util.cpp`](https://github.com/iyouthy/godot-recycler-view/blob/main/src/diff_util.cpp) (DiffUtil)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["List Core"]
  node_rv["RecyclerView<br/>[recycler_view.cpp]"]
  node_adapter["Adapter<br/>[adapter.cpp]"]
  node_holder["ViewHolder<br/>[view_holder.cpp]"]
  node_recycler["Recycler<br/>[recycler.cpp]"]
  node_pool["Recycled Pool"]
  node_state["List State<br/>[state.cpp]"]
end

subgraph group_layout["Layout Strategies"]
  node_layoutbase["Layout Manager<br/>[layout_manager.cpp]"]
  node_linear["Linear Layout"]
  node_grid["Grid Layout"]
  node_staggered["Staggered Layout"]
  node_span["Span Lookup"]
end

subgraph group_updates["Data Updates"]
  node_listadapter["ListAdapter<br/>[list_adapter.cpp]"]
  node_diff["DiffUtil<br/>[diff_util.cpp]"]
  node_diffalgo["Diff Algorithm<br/>[diff_algo.cpp]"]
end

subgraph group_interaction["Interaction Effects"]
  node_animator["Item Animator"]
  node_touch["Touch Helper"]
  node_snap["Snap Helper<br/>[snap_helper.cpp]"]
  node_decoration["Item Decoration"]
  node_scroll["Scroll Support<br/>[fling_scroller.cpp]"]
end

node_client(("GDScript Client"))

node_client -->|"configures"| node_rv
node_client -->|"supplies"| node_adapter
node_client -->|"selects"| node_layoutbase
node_rv -->|"queries data"| node_adapter
node_rv -->|"dispatches layout"| node_layoutbase
node_rv -->|"updates"| node_state
node_rv -->|"obtains views"| node_recycler
node_recycler -->|"creates and binds"| node_adapter
node_recycler -->|"reuses holders"| node_pool
node_recycler -->|"manages"| node_holder
node_linear -->|"positions views"| node_rv
node_grid -->|"queries spans"| node_span
node_listadapter -->|"submits lists"| node_diff
node_diff -->|"computes edits"| node_diffalgo
node_adapter -->|"notifies updates"| node_rv
node_rv -->|"animates changes"| node_animator
node_rv -->|"handles gestures"| node_touch
node_rv -->|"settles scrolling"| node_snap
node_rv -->|"draws insets"| node_decoration
node_rv -->|"drives fling"| node_scroll

click node_rv "https://github.com/iyouthy/godot-recycler-view/blob/main/src/recycler_view.cpp"
click node_adapter "https://github.com/iyouthy/godot-recycler-view/blob/main/src/adapter.cpp"
click node_holder "https://github.com/iyouthy/godot-recycler-view/blob/main/src/view_holder.cpp"
click node_recycler "https://github.com/iyouthy/godot-recycler-view/blob/main/src/recycler.cpp"
click node_pool "https://github.com/iyouthy/godot-recycler-view/blob/main/src/recycled_view_pool.h"
click node_state "https://github.com/iyouthy/godot-recycler-view/blob/main/src/state.cpp"
click node_layoutbase "https://github.com/iyouthy/godot-recycler-view/blob/main/src/layout_manager.cpp"
click node_linear "https://github.com/iyouthy/godot-recycler-view/blob/main/src/linear_layout_manager.cpp"
click node_grid "https://github.com/iyouthy/godot-recycler-view/blob/main/src/grid_layout_manager.cpp"
click node_staggered "https://github.com/iyouthy/godot-recycler-view/blob/main/src/staggered_grid_layout_manager.cpp"
click node_span "https://github.com/iyouthy/godot-recycler-view/blob/main/src/span_size_lookup.cpp"
click node_listadapter "https://github.com/iyouthy/godot-recycler-view/blob/main/src/list_adapter.cpp"
click node_diff "https://github.com/iyouthy/godot-recycler-view/blob/main/src/diff_util.cpp"
click node_diffalgo "https://github.com/iyouthy/godot-recycler-view/blob/main/src/diff_algo.cpp"
click node_animator "https://github.com/iyouthy/godot-recycler-view/blob/main/src/default_item_animator.cpp"
click node_touch "https://github.com/iyouthy/godot-recycler-view/blob/main/src/item_touch_helper.cpp"
click node_snap "https://github.com/iyouthy/godot-recycler-view/blob/main/src/snap_helper.cpp"
click node_decoration "https://github.com/iyouthy/godot-recycler-view/blob/main/src/item_decoration.cpp"
click node_scroll "https://github.com/iyouthy/godot-recycler-view/blob/main/src/fling_scroller.cpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_rv,node_adapter,node_holder,node_recycler,node_pool,node_state,node_client toneBlue
class node_layoutbase,node_linear,node_grid,node_staggered,node_span toneAmber
class node_listadapter,node_diff,node_diffalgo toneMint
class node_animator,node_touch,node_snap,node_decoration,node_scroll toneRose
```

## Components

### List Core

- [RecyclerView](https://github.com/iyouthy/godot-recycler-view/blob/main/src/recycler_view.cpp): `src/recycler_view.cpp`
- [Adapter](https://github.com/iyouthy/godot-recycler-view/blob/main/src/adapter.cpp): `src/adapter.cpp`
- [ViewHolder](https://github.com/iyouthy/godot-recycler-view/blob/main/src/view_holder.cpp): `src/view_holder.cpp`
- [Recycler](https://github.com/iyouthy/godot-recycler-view/blob/main/src/recycler.cpp): `src/recycler.cpp`
- [Recycled Pool](https://github.com/iyouthy/godot-recycler-view/blob/main/src/recycled_view_pool.h): `src/recycled_view_pool.h`
- [List State](https://github.com/iyouthy/godot-recycler-view/blob/main/src/state.cpp): `src/state.cpp`

### Layout Strategies

- [Layout Manager](https://github.com/iyouthy/godot-recycler-view/blob/main/src/layout_manager.cpp): `src/layout_manager.cpp`
- [Linear Layout](https://github.com/iyouthy/godot-recycler-view/blob/main/src/linear_layout_manager.cpp): `src/linear_layout_manager.cpp`
- [Grid Layout](https://github.com/iyouthy/godot-recycler-view/blob/main/src/grid_layout_manager.cpp): `src/grid_layout_manager.cpp`
- [Staggered Layout](https://github.com/iyouthy/godot-recycler-view/blob/main/src/staggered_grid_layout_manager.cpp): `src/staggered_grid_layout_manager.cpp`
- [Span Lookup](https://github.com/iyouthy/godot-recycler-view/blob/main/src/span_size_lookup.cpp): `src/span_size_lookup.cpp`

### Data Updates

- [ListAdapter](https://github.com/iyouthy/godot-recycler-view/blob/main/src/list_adapter.cpp): `src/list_adapter.cpp`
- [DiffUtil](https://github.com/iyouthy/godot-recycler-view/blob/main/src/diff_util.cpp): `src/diff_util.cpp`
- [Diff Algorithm](https://github.com/iyouthy/godot-recycler-view/blob/main/src/diff_algo.cpp): `src/diff_algo.cpp`

### Interaction Effects

- [Item Animator](https://github.com/iyouthy/godot-recycler-view/blob/main/src/default_item_animator.cpp): `src/default_item_animator.cpp`
- [Touch Helper](https://github.com/iyouthy/godot-recycler-view/blob/main/src/item_touch_helper.cpp): `src/item_touch_helper.cpp`
- [Snap Helper](https://github.com/iyouthy/godot-recycler-view/blob/main/src/snap_helper.cpp): `src/snap_helper.cpp`
- [Item Decoration](https://github.com/iyouthy/godot-recycler-view/blob/main/src/item_decoration.cpp): `src/item_decoration.cpp`
- [Scroll Support](https://github.com/iyouthy/godot-recycler-view/blob/main/src/fling_scroller.cpp): `src/fling_scroller.cpp`

### Other components

- **GDScript Client**

## Connections

- GDScript Client → RecyclerView: configures
- GDScript Client → Adapter: supplies
- GDScript Client → Layout Manager: selects
- RecyclerView → Adapter: queries data
- RecyclerView → Layout Manager: dispatches layout
- RecyclerView → List State: updates
- RecyclerView → Recycler: obtains views
- Recycler → Adapter: creates and binds
- Recycler → Recycled Pool: reuses holders
- Recycler → ViewHolder: manages
- Linear Layout → RecyclerView: positions views
- Grid Layout → Span Lookup: queries spans
- ListAdapter → DiffUtil: submits lists
- DiffUtil → Diff Algorithm: computes edits
- Adapter → RecyclerView: notifies updates
- RecyclerView → Item Animator: animates changes
- RecyclerView → Touch Helper: handles gestures
- RecyclerView → Snap Helper: settles scrolling
- RecyclerView → Item Decoration: draws insets
- RecyclerView → Scroll Support: drives fling