Tab Hiệu ứng — Các đối tượng liên hệ với nhau như thế nào

⚠️ CẢNH BÁO ĐỘ TƯƠI — chưa đối chiếu lại sau G2–G5. Tài liệu này sửa lần cuối trước đợt G2–G5 (hợp nhất hai đường render, chọn nhiều clip, keyframe automation, thư viện ảnh động). Kiểm bằng grep: nó không nhắc tới một tính năng nào trong số đó. Phần mô tả giao diện vì thế có thể đã lạc hậu. Khi nghi ngờ, tin test và kịch bản UiDrive trước.

Tài liệu dành cho người dùng. Mục tiêu: hiểu được Effect, Look, Timeline, Track, Clip, Vùng chọn và Sơ đồ dây gắn kết ra sao, để biết “bấm cái gì thì ra cái gì”. Nội dung mô tả đúng cách phần mềm đang chạy thật (rà từ mã nguồn), không phải tính năng dự kiến.

Nếu bạn chỉ nhớ được một câu: effect là công thức, look là món nấu ra từ công thức, clip là suất phục vụ món đó lên dòng thời gian — và cảnh là cả buổi diễn mà công tắc trên bo chọn để chạy. Bốn tầng, bốn tên, không tên nào dùng thay tên nào.

1. Bảy khái niệm cốt lõi, một câu chuyện

Hãy hình dung bạn đang dàn một màn trình diễn ánh sáng. Có 7 khái niệm, xếp thành hai “thế giới” và một cây cầu nối:

Thế giới vật lý — bạn có gì để thắp sáng (Tab Sơ đồ dây):

⚠️ Collection CHƯA DÙNG ĐƯỢC trong bản hiện tại (audit 2026-07-16). Mô hình dữ liệu và phép gán (WiringV2Mutations.SetLedsCollection) đã có trong lõi, nhưng chưa có lệnh/nút nào trên giao diện để gom LED thành Collection — không code path nào gán Led.CollectionId, và migrator V1→V2 cũng chưa map Layer → CollectionId. Hệ quả: mọi Collection đều rỗng, nên kiểu vùng chọn “Theo Collection” ở §3 hiện không chọn được LED nào. Phần nói về Collection dưới đây mô tả thiết kế dự kiến, chưa phải thứ bạn bấm được hôm nay.

Thế giới sáng tạo — bạn muốn chúng sáng thế nào (Tab Hiệu ứng):

Chữ “cảnh” KHÔNG còn dùng cho vật này. Theo ADR-0012, “cảnh” nay là đơn vị NẠP ĐƯỢC mà công tắc trên bo chọn — một tầng đứng TRÊN timeline. Trên giao diện, thứ bạn thao tác vẫn gọi là clip; thứ clip trỏ tới gọi là look. Xem §1.1.

Cây cầu — Vùng chọn (Selection): mỗi Clip mang theo một Vùng chọn LED trả lời câu hỏi “effect này sáng trên những LED nào?”. Đây chính là chỗ nối thế giới sáng tạo vào thế giới vật lý.

Và tất cả nằm trên:

1.1. Ba tầng ở phía TRÊN clip: chế độ → cảnh → clip

Ba khái niệm dưới đây trả lời câu hỏi “khi rút dây máy tính ra, mạch biết phải chạy cái gì?”. Chúng là quyết định D1 của ADR-0012.

Đọc từ trên xuống: gạt công tắc → ra một chế độ → chế độ trỏ tới một cảnh → cảnh đó có timeline riêng → trên timeline là các clip → mỗi clip trỏ tới một look → look chứa các effect.

Ba điều dễ nhầm, nói thẳng ra để khỏi nhầm:

• Cảnh không phải một cách gọi khác của clip. Một cảnh chứa cả một timeline; một clip là một ô trên timeline đó. Trước đây phần mềm từng gọi cái ô ấy là “cảnh”, và đó chính là sự nhầm mà ADR-0012 sinh ra để dọn.
• Look không phải clip. Look là nội dung; clip là một lần đặt nội dung ấy vào một khoảng thời gian, trên một vùng LED. Hai clip khác nhau dùng chung một look là chuyện bình thường — sửa look thì cả hai đổi theo.
• Số cảnh không bị chặn ở 4. 4 là số trạng thái công tắc, không phải số cảnh. Nhiều chế độ trỏ chung một cảnh là hợp lệ, và riêng chế độ tự-động-theo-nhạc đã tham chiếu tới ba cảnh (“khởi động”, “có nhạc”, “im lặng”).

✅ Tầng cảnh ĐÃ BẤM ĐƯỢC — bảng "Cảnh" nay nằm ở sidebar bên trái của Dòng thời gian (dock đáy), ngay sát cạnh timeline (Views/TimelineView.axaml nhúng Views/SceneTreeView.axaml làm sidebar trái với dải vạch Accent Bar nổi bật khi cảnh đang mở; Dock trái phía trên có hai tab: "Thư viện Hiệu ứng" và "Cài đặt sẵn" theo ModuleManifests.cs:113-114). Từ đó bạn thêm / đổi tên / xoá / chọn cảnh, và đặt bảng chế độ (vị trí công tắc nào nạp cảnh nào) trong khối gấp được ngay dưới danh sách cảnh. Lệnh chạy thật ở SceneEditService.cs:22-31 (Activate · Add · Rename · Remove · SetMode). Tệp dự án .rsp mang tầng này từ schema bản 4 (ProjectFormat.CurrentSchemaVersion = 4).

Bố cục mới chuẩn hóa theo luồng thị giác 1:1: chọn Cảnh ở cột trái $\rightarrow$ Dòng thời gian tương ứng bung ra ở bên phải, đồng thời giải phóng 100% không gian dock trái cho Thư viện hiệu ứng và Cài đặt sẵn.

⚠ Còn nợ thật: phần chạy trên mạch vẫn chờ đường xuất .rfx2 được nối hai đầu — firmware chưa đọc .rfx2. Đó là món nợ duy nhất còn lại của mục này.

2. Sơ đồ quan hệ

        THẾ GIỚI VẬT LÝ (Tab Sơ đồ dây)                THẾ GIỚI SÁNG TẠO (Tab Hiệu ứng)
   ┌───────────────────────────────────┐        ┌──────────────────────────────────────┐
   │ Controller ─cổng→ Strip ─┬→ LED    │        │  Thư viện Hiệu ứng                    │
   │                          │         │        │  (Rainbow, Chase, Fire, Plasma, …)    │
   │            Collection ◄──┘         │        └───────────────┬──────────────────────┘
   │            (nhóm LED có tên)       │                        │ kéo vào Timeline / bấm Apply
   └──────────────┬────────────────────┘                        ▼
                  │                                   ┌────────  Look  ─────────┐
                  │                                   │  1 (hoặc nhiều) Effect  │
                  │                                   │  + tham số, blend, opacity
                  │                                   └───────────┬─────────────┘
                  │                                               │  LookRef (trỏ tới Look)
                  │   Selection (Vùng chọn)                       ▼
                  └───────────────────────────────────►   ┌───  Clip  ───┐
                      "effect này sáng trên LED nào"       │ Start, Duration
                      (Tất cả / Chữ nhật / LED cụ thể /     │ + Vùng chọn LED
                       theo Collection)                     │ + ghi đè tham số
                                                            └──────┬───────┘
                                                                   │ nằm trên
                                                                   ▼
                                                              Track (Lớp) ──blend/opacity──┐
                                                                   │ thuộc                 │ nhiều Track
                                                                   ▼                       │ chồng lên nhau
                                                              Timeline ◄───────────────────┘
                                                                   │ thuộc
                                                                   ▼
                                                            Cảnh (Scene)  ── đơn vị NẠP ĐƯỢC
                                                                   ▲
                                                                   │ trỏ tới
                                                          chế độ (2 cần gạt: ↓↓ ↑↓ ↓↑ ↑↑)

Đọc sơ đồ theo một câu:

Bạn chọn một Effect từ Thư viện → nó được gói thành một Look → Look được đặt lên Timeline thành một Clip trong một Track → Clip mang một Vùng chọn trỏ tới các LED / Collection trong Sơ đồ dây → khi chạy, effect chỉ tô màu lên đúng nhóm LED đó.

Và một câu nữa cho hai tầng trên cùng:

Cả cái Timeline vừa nói nằm trong một Cảnh; gạt hai cần gạt trên bo là chọn chế độ, và chế độ quyết định cảnh nào được nạp ra chạy. Hôm nay mọi dự án có đúng một cảnh nên bốn vị trí công tắc đều ra cùng một thứ — xem §1.1.

3. Quan hệ chi tiết (ai chứa ai, ai trỏ ai)

• Project chứa: Sơ đồ dây, kho Look, kho Cảnh, bảng chế độ, và Timeline của cảnh đang mở.
  • Kho Look và kho Cảnh là hai danh sách khác nhau, đừng lẫn: kho Look là những gói effect mà clip trỏ tới; kho Cảnh là những đơn vị nạp được mà công tắc trên bo chọn.
  • Bảng chế độ ghi vị trí công tắc nào → nạp cảnh nào. Nó là dữ liệu, không phải bốn ô cố định — bo sau có thêm công tắc thì chỉ thêm dòng.
• Look chứa: một danh sách Effect (mỗi effect có tham số, kiểu hòa trộn, độ mờ riêng). Bản thân Effect không tự biết nó chiếu lên LED nào — việc đó do Clip quyết định.
• Cảnh chứa: một Timeline của riêng nó, cộng cấu hình “Nháy theo nhạc” riêng (cảnh “khởi động” tắt nháy, cảnh “sàn nhảy” bật mạnh — đặt theo cảnh, không theo clip).
• Timeline chứa: các Track; mỗi Track chứa các Clip.
• Clip KHÔNG chứa Look — nó “trỏ” tới Look bằng một tham chiếu (LookRef). Nhờ vậy một Look có thể được dùng lại ở nhiều Clip khác nhau.
• Clip mang thêm hai thứ của riêng nó:
  • Vùng chọn (Selection): những LED mà effect trong Look sẽ tô. Có 5 kiểu (LedSelectionKind), không phải 4:
    • Tất cả — mọi LED trong sơ đồ.
    • Hình chữ nhật — mọi LED nằm trong một khung.
    • LED cụ thể — bạn tự bấm chọn từng LED trên canvas. Đây là một ảnh chụp: danh sách LED id tại thời điểm chọn. Sơ đồ đổi về sau thì clip giữ nguyên danh sách cũ, im lặng.
    • Theo dải LED (Strip) — trỏ tới một dải LED trên sơ đồ. Ràng buộc động: thêm/bớt LED trong dải ấy thì mọi clip trỏ tới nó tự đổi theo, không phải chọn lại. Đây là kiểu bạn nên dùng khi muốn nhắm đúng một Nhóm đã dựng sẵn lúc vẽ — trước khi có nó, muốn làm việc đó vẫn phải click từng LED.
    • Theo Collection — trỏ tới một nhóm LED có tên; cũng là liên kết động. ⚠️ Chưa dùng được — không còn lối tạo/gán Collection từ giao diện kể từ Wave 2, nên nhóm luôn rỗng (xem cảnh báo ở §1). Kiểu này chỉ còn để đọc được dự án cũ; dự án mới hãy dùng Theo dải LED. Bốn kiểu còn lại chạy bình thường.
  • Ghi đè tham số: đổi tham số của effect chỉ cho riêng Clip này, không đụng tới Look gốc.

Điểm mấu chốt cần nhớ: “Sáng cái gì” nằm ở Look/Effect; “sáng ở đâu” nằm ở Vùng chọn của Clip; “sáng lúc nào” nằm ở vị trí Clip trên Timeline.

4. Vùng chọn quyết định cả “ở đâu” lẫn “hình dạng”

Điều nhiều người bất ngờ: Vùng chọn không chỉ lọc LED, nó còn định hình toạ độ cho effect. Khi chạy, phần mềm lấy các LED được chọn, chuẩn hoá vị trí của chúng về khoảng 0→1 rồi mới đưa cho effect vẽ.

Hệ quả thực tế:

• Cùng một effect Radial Wave (sóng lan từ tâm), nếu Vùng chọn là “Cánh trái” thì tâm sóng nằm giữa cánh trái; nếu là “Cả sân khấu” thì tâm nằm giữa toàn bộ.
• Vì thế, đổi Vùng chọn không chỉ đổi chỗ sáng mà có thể đổi cả dáng chuyển động của hiệu ứng.

5. Nhiều Track chồng lên nhau ra sao

Khi có nhiều Track cùng chạy tại một thời điểm:

• Các Track được hoà trộn theo thứ tự từ dưới lên: Track đứng sau (phía trên trong danh sách) phủ lên Track trước.
• Mỗi Track có kiểu hoà trộn (Normal/Add/Multiply/Screen) và độ mờ riêng.
• Track bị tắt tiếng (mute) hoặc độ mờ = 0 thì bị bỏ qua; có Track Solo thì chỉ Track đó phát.

Nhờ vậy bạn có thể để nền “Gradient” ở Track dưới và “Sparkle” lấp lánh ở Track trên, chúng cộng hưởng thành một hiệu ứng phức hợp.

6. Các khu vực trong Tab Hiệu ứng

Dock trái có đúng hai tab: "Thư viện Hiệu ứng" và "Cài đặt sẵn" (ModuleManifests.cs:113-114). Cảnh được chuyển về làm Sidebar bên trái của Dòng thời gian (TimelineView.axaml), tạo luồng thao tác trực quan: chọn Cảnh bên trái $\rightarrow$ Dòng thời gian bên phải nạp đúng các track và clip của Cảnh đó. Khi cần xếp chồng hiệu ứng, người dùng thêm nhiều Track trên Dòng thời gian thay vì lồng nhiều effect trong một clip đơn lẻ.

7. Làm một hiệu ứng hiện lên LED — từng bước (theo đúng luồng hiện tại)

1. Dựng sơ đồ dây trước (Tab Sơ đồ dây): đặt Controller → Strip → LED. ⚠️ (Bản hiện tại chưa có lệnh gom LED thành Collection — xem §1. Muốn nhắm theo khu vực, hãy dùng Hình chữ nhật hoặc LED cụ thể ở bước 4.)
2. Sang Tab Hiệu ứng → Thư viện: bấm Apply hoặc kéo một effect thả xuống một Track trên Timeline. → Phần mềm tự tạo Look + Clip + Effect cùng lúc, và tự chọn Clip vừa tạo.
3. Chỉnh tham số trong Inspector (màu, tốc độ, độ mờ…). Các thay đổi này là ghi đè cho Clip đang chọn.
4. Chọn vùng LED trong Inspector (chỉ bật khi đang chọn 1 Clip):
   • Toàn bộ, hoặc
   • Hình chữ nhật qua các ô X/Y/W/H nâng cao, hoặc
   • Theo dải LED — chọn một dải LED trên sơ đồ làm vùng cho clip (ràng buộc động), hoặc
   • bấm “Chọn LED cho clip” để bật chế độ chọn LED ngay trên Preview của tab Hiệu ứng. (Nút bên cạnh, “Chọn LED cho track”, làm việc tương tự cho cả track.) Tên nút thật lấy từ Strings.resx:1299 — bản trước của tài liệu gọi nó là “Chọn LED trên canvas”, không có nút nào mang tên đó.
   • Khi đó bạn có thể click từng LED hoặc kéo khung để chọn trực tiếp trên preview; tắt chế độ này thì vùng chọn được ghi vào Clip.
5. Xem Preview ở giữa; bấm Play trên Timeline để chạy theo thời gian.

Mẹo: Muốn cùng một hiệu ứng chạy ở hai khu vực khác nhau, hãy tạo hai Clip (mỗi Clip một Vùng chọn). Muốn hai hiệu ứng khác nhau chồng nhau, đặt chúng ở hai Track.

8. Bảng thuật ngữ nhanh

Trang chị em cũ: 02-Danh-gia-mo-hinh-va-Khuyen-nghi.md (đánh giá mô hình + khuyến nghị P1–P5) đã chuyển vào archive/audits/ ngày 2026-08-27 và KHÔNG còn được liên kết từ tầng hiện hành: P1–P4 trong đó đã làm xong, và mọi tệp:dòng của nó mô tả thế giới trước đợt đổi tên Scene→Look (SceneRef không còn tồn tại, TickV2 không tồn tại). Đọc nó để biết ý đồ, đừng tra cứu theo nó.