infinite-webgl-grid

Skill: infinite-webgl-grid

Component Three.js thuần — lưới N×N tile ảnh cố định, kéo (pointer) hoặc cuộn (wheel) để duyệt như thể lưới trải dài vô hạn theo mọi hướng, dùng kỹ thuật coordinate-wrapping (modulo offset), không phải sinh/huỷ mesh liên tục.

WHAT

Purpose và context

• Purpose: dựng lưới ảnh WebGL N×N duyệt vô hạn mọi hướng (kéo/cuộn) bằng coordinate-wrapping, ưu tiên copy nguyên bản gốc ở Rheinmir/uiux-asset.
• Trigger (when to use):
  • Portfolio/gallery/poster-wall cần cảm giác "duyệt vô hạn" theo mọi hướng (không phải cuộn 1 chiều thông thường).
  • User nói "lưới ảnh vô hạn", "infinite scroll grid webgl", "draggable image wall", "poster wall cuộn vô hạn".
• Non-goals:
  • KHÔNG dùng khi cần particle hội tụ thành MỘT ảnh cụ thể theo scroll progress (đó là threejs-particle-morph — có state "đã tới đích", còn đây không có đích, chỉ duyệt liên tục).
  • KHÔNG dùng cho hiệu ứng chuyển giữa 2 ảnh trên cùng 1 khung (đó là blur).

Mental model

offset ảo (kéo/cuộn/inertia) → mỗi mesh cố định: wrap(localX - offset.x) → vị trí hiển thị → chỉ số tile ảo đổi → đổi material.map từ pool texture cố định. Camera đứng yên, không add/remove mesh lúc chạy (chi tiết: Reference — Cơ chế).

Input và output contract

	Field	Required?	Ý nghĩa
In	ảnh/nội dung + màu	không	thiếu → demo tự vẽ placeholder canvas, chạy offline
In	ràng buộc dự án: được kéo lib/file ngoài không	có	được → bản gốc; không → assets/ vanilla
In	gridSize/tileSize/gap/poolSize	không	tham số khởi tạo InfiniteGrid
Out	file .html (+ _assets/) hoặc demo.html/.css/.js đã adapt trong dự án	có	giữ comment ghi công dòng đầu nếu là bản gốc
Out	bằng chứng verify Playwright	có	ảnh trước/giữa/sau khi kéo 4 hướng + console sạch

Rules và capabilities

• RULE-01 (MUST): Giới hạn tile/texture đồng thời: mobile GPU giới hạn số texture unit hoạt động cùng lúc. Giữ lưới hiển thị thực tế (không tính vòng đệm wrap) ở khoảng ≤ 5×5 tile cùng lúc; demo mặc định gridSize=7 (5 hiển thị + 1 vòng đệm mỗi bên để tile nhảy cóc mượt, không pop-in). Cần nhiều ảnh khác nhau hơn số tile hiển thị → dùng texture atlas (gộp nhiều ảnh vào 1 texture, đổi UV offset thay vì đổi material.map riêng từng texture) thay vì tăng poolSize vô hạn — mỗi texture riêng vẫn tốn 1 texture unit dù không hiển thị cùng lúc nếu code giữ tham chiếu.
• RULE-02 (MUST): Passive: false bắt buộc: listener wheel và pointermove phải đăng ký { passive: false } rồi gọi preventDefault() đúng chỗ (chỉ khi đang kéo hoặc đang ở trong canvas) — thiếu cờ này, trình duyệt hiện đại mặc định passive nên preventDefault() bị bỏ qua ÂM THẦM (không lỗi, không cảnh báo) và trang nền vẫn cuộn/zoom song song với lưới, gây giật/xung đột trên mobile. CSS touch-action: none trên container là điều kiện cần đi kèm, không thay thế được preventDefault.
• RULE-03 (SHOULD): Ortho camera dùng cho demo (lưới phẳng, không méo phối cảnh) — đổi sang PerspectiveCamera nếu cần hiệu ứng chiều sâu (tile xa mờ/nhỏ dần), khi đó công thức wrap vẫn giữ nguyên, chỉ đổi cách map world-unit sang pixel.
• RULE-04 (MUST): Verify bằng playwright-verify — chụp trước/giữa/sau khi kéo mạnh (test cả 4 hướng), đọc console (context WebGL lỗi thường im lặng ở canvas, không throw JS error rõ ràng).
• Capabilities: đọc/copy file từ repo asset ngoài (hoặc assets/ của skill); ghi file vào dự án; phục vụ qua HTTP cục bộ; điều khiển trình duyệt headless để chụp + đọc console.

Failure boundaries

• Dự án không được kéo lib ngoài → partial hợp lệ: dùng bản rút gọn assets/ thay bản gốc.
• Mở qua file:// → texture/asset lỗi → blocked cho tới khi chạy qua HTTP.
• Console có lỗi WebGL hoặc trang nền cuộn song song lưới → failed verify, sửa (passive:false + touch-action: none) rồi verify lại.
• Yêu cầu thật ra là particle hội tụ/chuyển 2 ảnh → clarify, chuyển threejs-particle-morph / blur.

HOW

Main workflow

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	judgment	yêu cầu	Xác nhận đúng skill (lưới duyệt vô hạn, không có đích) và chọn bản gốc hay assets/	nguồn đã chọn	không được kéo lib ngoài → B01
W02	effect	pen gốc	Mở link chạy xem hiệu ứng → copy nguyên file .html (+ _assets/) vào dự án, giữ comment ghi công	file trong dự án	—
W03	judgment	file đã copy	Chỉ sửa nội dung/ảnh/màu	file đã adapt	—
W04	effect	file	Chạy local qua HTTP, không file://	trang chạy	lỗi asset → kiểm lại đường dẫn
W05	deterministic	trang	Verify bằng playwright-verify: chụp trước/giữa/sau kéo mạnh 4 hướng + đọc console	ảnh + console sạch	lỗi → sửa, lặp W04

Chi tiết từng bước (nguồn chân lý cho W01–W05):

Bản gốc — dùng TRƯỚC (copy nguyên file, đừng viết lại)

Code gốc NGUYÊN VĂN của tác giả (CodePen public = MIT) nằm ở repo ngoài Rheinmir/uiux-asset — gallery chạy thật: https://rheinmir.github.io/uiux-asset/scroll-effects/ . Quy trình: mở link chạy để xem đúng hiệu ứng → copy nguyên file .html (+ thư mục _assets/ nếu file trỏ tới) vào dự án → giữ comment ghi công dòng đầu → chỉ sửa nội dung/ảnh/màu. Chạy local qua HTTP, không file://. git clone --depth 1 https://github.com/Rheinmir/uiux-asset nếu cần cả bộ offline.

Pen gốc — tác giả	Link
Infinite Scrollable and Draggable WebGL Grid — ReGGae	chạy · code
Infinite 3D Poster Scroll Wall — photodow	chạy · code
Infinite Scrolling with Image Cards — jkantner	chạy · code

assets/ trong skill này chỉ là bản rút gọn vanilla tự viết — dùng khi dự án KHÔNG được kéo lib ngoài; mặc định dùng bản gốc ở trên.

Branches

ID	Kind	Guard	Hành vi	Skip / failure	Rejoin
B01	conditional_required	dự án KHÔNG được kéo lib ngoài	dùng assets/demo.html + demo.css + demo.js, ADAPT tham số và thay placeholder bằng ảnh thật (mục Assets)	—	W04
B02	user_optional	cần hiệu ứng chiều sâu	đổi Ortho sang PerspectiveCamera, giữ công thức wrap, chỉ đổi map world-unit → pixel	—	W05
B03	conditional_required	cần nhiều ảnh khác nhau hơn số tile hiển thị	dùng texture atlas (đổi UV offset) thay vì tăng poolSize	—	W05

Validation và stopping

Xong khi Playwright chụp đủ trước/giữa/sau kéo cả 4 hướng, lưới không pop-in, trang nền không cuộn theo, console không lỗi (lỗi WebGL thường im lặng — phải đọc console chứ không chỉ nhìn ảnh).

Examples

• Positive: "làm poster wall cuộn vô hạn cho portfolio" → copy infinite-3d-poster-scroll-wall.html từ Rheinmir/uiux-asset, thay ảnh, chạy local qua HTTP, Playwright kéo 4 hướng → tile nhảy cóc mượt, console sạch.
• Boundary/failure: dùng assets/demo.js nhưng đăng ký wheel không { passive: false } → preventDefault() bị bỏ qua âm thầm, trang nền cuộn cùng lưới → verify fail, thêm cờ + touch-action: none rồi chạy lại.

Reference — Assets

assets/demo.html + assets/demo.css + assets/demo.js — đọc rồi ADAPT (đổi gridSize/tileSize/gap/poolSize khi khởi tạo InfiniteGrid, thay _drawPlaceholder() bằng ảnh thật qua THREE.TextureLoader load URL thay vì data URL canvas). Demo tự vẽ placeholder (canvas số + màu hash) nên chạy được ngay không cần ảnh/network.

Reference — Cơ chế

• Mesh cố định, không sinh thêm: gridSize × gridSize mesh (PlaneGeometry dùng chung 1 instance + material riêng mỗi mesh) dựng một lần lúc init, KHÔNG BAO GIỜ add/remove mesh lúc chạy — khác hẳn cách làm ngây thơ "sinh mesh mới khi kéo tới vùng chưa có".
• Offset ảo, không di chuyển camera ra xa vô hạn: kéo/cuộn chỉ cộng dồn vào offset.x/offset.y (số float, có thể tăng vô hạn theo lý thuyết, không bao giờ chạm giới hạn thực tế). Camera đứng yên.
• Wrap bằng modulo: mỗi mesh có toạ độ cục bộ cố định localX/localY (vị trí trong lưới N×N gốc). Vị trí hiển thị thật mỗi frame = wrap(localX - offset.x), với wrap(raw) = ((raw + half) % full + full) % full - half (full = gridSize*pitch, half = full/2) — gấp toạ độ vô hạn về dải hiển thị quanh tâm, đúng công thức mod chuẩn cho kỹ thuật này.
• Texture reuse khi tile nhảy cóc: mỗi mesh chỉ đổi material.map khi "chỉ số tile ảo" của nó đổi (tính từ wrapped_position + offset, làm tròn theo pitch) — tức đúng lúc tile rời khung nhìn một bên và xuất hiện lại bên đối diện. Texture lấy từ pool cố định (poolSize texture load một lần qua THREE.TextureLoader), KHÔNG tạo texture mới mỗi lần nhảy cóc.
• Placeholder không phụ thuộc mạng: pool texture sinh từ <canvas> vẽ số + màu (golden-angle hue spread để phân biệt bằng mắt), canvas.toDataURL() rồi vẫn nạp qua THREE.TextureLoader.load(dataUrl) — demo chạy offline nhưng vẫn đúng đường API load ảnh thật (khi thay ảnh thật chỉ cần đổi URL, không đổi luồng code).
• Inertia: pointer drag ghi velocity (delta di chuyển của lần pointermove cuối); khi thả tay, mỗi frame offset += velocity; velocity *= damping (0.92) cho tới khi dưới ngưỡng — lerp về 0 dần, không phải mô phỏng vật lý thật.
• Cleanup: destroy() gỡ pointerdown/pointermove/pointerup/pointercancel/wheel/resize listener, dispose từng material, dispose geometry dùng chung (1 lần), dispose từng texture trong pool (1 lần — KHÔNG dispose theo mesh vì texture được nhiều mesh share), dispose renderer, gỡ canvas khỏi DOM.

Origin