Mercurial

comparison infinite_canvas/docs/entities-and-components.md @ 278:8d560f50ed4c

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Improve infinite canvas interactions and browser chrome Render Lucide icons directly with Raylib, add searchable icon browsing, robust text editing, entity lifecycle animations, z-order-safe input, semantic themes, and animated editable browser controls. Document rendering, pinning, context, and component extension for future agents. Co-authored-by: Copilot <[email protected]> Copilot-Session: f68442b1-fa8f-46a0-9689-81710613bbd4
author MrJuneJune <me@mrjunejune.com>
date Mon, 17 Aug 2026 22:16:14 -0700
parents
children 49e9e591c9bb
comparison
equal deleted inserted replaced
277:1d99147f520c 278:8d560f50ed4c
1 # Entities and Components
2
3 ## Retained data, immediate drawing
4
5 `Canvas_Scene` stores an arena-backed array of `Canvas_Entity`. Each entity has:
6
7 - a stable `id` for external resources such as browser views;
8 - `type`, world `position`, and world `size`;
9 - generic semantic fields: `text`, `value`, and `active`;
10 - interaction/animation state;
11 - pinning state in both world and screen coordinates.
12
13 The scene is retained, but the draw list is rebuilt every frame. This keeps
14 interaction and context state stable while allowing normal Raylib immediate-mode
15 drawing.
16
17 Each entity also owns lifecycle state. `visibility_amount` eases from zero to
18 one after creation. Delete and developer Clear mark entities as `removing`, ease
19 them back to zero, then compact the retained array. Raylib colors, native CEF
20 texture tints, and WebAssembly overlay opacity all consume the same eased value.
21
22 ## Adding a component
23
24 Wire every relevant surface, not only drawing:
25
26 1. Add the enum value in `canvas.h`.
27 2. Set useful size, text, and state defaults in `Canvas_Scene_Add()`.
28 3. Add bounds/picking behavior in `Canvas_Entity_Bounds()` and
29 `Canvas_Entity_Contains()`.
30 4. Add click behavior in `Canvas_Scene_Activate()` and specialized update logic
31 in `Canvas_Scene_Update_Interaction()` when needed.
32 5. Draw it in `Canvas_Draw_Entity()` and support selection in
33 `Canvas_Draw_Selection()`.
34 6. Return a readable label from `Canvas_Entity_Type_Name()`.
35 7. Serialize meaningful state in `Canvas_Context_Append_Entity_State()`.
36 8. Add focused tests in `canvas_test.c`.
37 9. If it owns external pixels or DOM, extend both web-surface backends and key
38 resources by stable entity ID.
39
40 Prefer a single entity for large compound views. The Lucide gallery is one
41 entity with virtualized internal rows, not 1,767 independently draggable scene
42 objects.
43
44 ## Input ownership
45
46 Input is resolved from most specialized to most general:
47
48 - developer UI;
49 - focused native CEF content;
50 - hovered/pressed scene entity;
51 - camera.
52
53 Open developer dropdowns are modal because Raygui draws their item list beyond
54 the panel rectangle and consumes outside clicks to close. While one is open,
55 neither native web surfaces nor canvas entities receive pointer input behind it.
56
57 Text editing blocks WASD/arrow camera movement. Scrollable entities consume an
58 unmodified wheel. Ctrl/Cmd + wheel remains available to the camera for anchored
59 zoom; an unmodified wheel outside a scrollable entity pans vertically.
60
61 Text areas keep cursor, selection anchor, and vertical scroll state on the
62 entity. Their visual-line layout is shared by drawing, hit testing, vertical
63 cursor movement, and caret visibility, so wrapped text and mouse selection use
64 the same geometry. Ctrl on Windows/Linux and Cmd on macOS drive select/copy/
65 cut/paste shortcuts; Ctrl or Option performs word navigation.