DEV Community: 天知道997 997

Building Purupuru Maker: A Browser-Based Image Wobble Tool with React, Canvas, and Three.js

天知道997 997 — Mon, 20 Jul 2026 09:43:01 +0000

Purupuru Maker is a lightweight browser tool for turning still images into soft, jelly-like wobble animations. The core idea is simple for the user: upload an image, paint the area that should move, tune the motion, and export the animation. Under the hood, the project combines React, TypeScript, Canvas 2D, Three.js, and browser-native media APIs to create an animation workflow that runs locally without sending user images to a server.

Why This Project Is Built as a Client-Side Tool

Image animation tools often feel heavier than they need to be. Many require installing desktop software, uploading artwork to a remote service, or learning a timeline-based editor before producing a simple animated sticker or avatar. Purupuru Maker takes the opposite approach: the entire editing and export pipeline runs in the browser.

That constraint shapes the technical design. The app needs to decode images, let users paint a motion mask, preview a real-time deformation effect, and export media using APIs that are widely available in modern browsers. It also needs to stay responsive while handling images up to practical web sizes. React manages the application interface, Canvas 2D handles direct mask editing, Three.js renders the deformable image mesh, and MediaRecorder or GIF encoding turns the preview into a downloadable file.

The High-Level Architecture

The application is built with Vite, React, and TypeScript. Vite keeps local development fast, while TypeScript is especially useful for the shared data structures that move through the editor: loaded image metadata, motion settings, mask state, export settings, and deformable mesh vertices.

The main workflow is organized around a few responsibilities:

Image loading normalizes the uploaded file into a browser-friendly bitmap.
Mask painting stores the user's brush strokes in a hidden canvas.
Mesh generation creates a grid of vertices over the image.
Mask sampling converts painted pixels into per-vertex motion weights.
Physics updates move the weighted vertices every animation frame.
Three.js renders the image texture on the deformed grid.
Export modules record or encode the rendered canvas locally.

This separation keeps the product easy to extend. For example, adding a new motion preset mostly means changing motion settings, while adding a new export format can live in the export layer without rewriting the editor.

Turning an Image into a Deformable Mesh

The wobble effect is based on a textured grid. Instead of drawing the uploaded image as a flat rectangle, the renderer maps it onto a plane made of many small triangles. Each vertex in the grid stores its original position, current position, UV coordinates, motion weight, velocity, and offset.

On desktop, the mesh uses a denser grid than on smaller screens, which helps balance visual quality and performance. The grid is converted into triangle indices, then passed to Three.js as a BufferGeometry. The uploaded image becomes a CanvasTexture, and a simple MeshBasicMaterial displays that texture without lighting complexity.

This approach is efficient because the browser's GPU handles most of the textured rendering work. Each frame only needs to update vertex positions, mark the position buffer as dirty, and let Three.js draw the result.

Painting Motion with a Canvas Mask

The user does not directly edit the image. Instead, Purupuru Maker keeps the original artwork intact and stores brush strokes in a separate motion mask. Canvas 2D is a strong fit for this job because it supports fast pointer-based drawing, erasing, alpha blending, and pixel reads.

When the user paints, the mask records where motion should happen and how strong that motion should be. A visible overlay can show the painted area during editing, but the underlying image remains unchanged. This makes the editor non-destructive and keeps the mental model simple: paint the parts that should wobble, erase the parts that should stay still.

Before previewing, the app samples the mask around every mesh vertex. The sampled mask value becomes the vertex's motion weight. A small edge fade reduces movement near image borders, and several smoothing passes blend neighboring weights so the deformation feels organic instead of jagged.

The Wobble Physics Model

The animation is not a single sine wave applied uniformly to the image. Each weighted vertex moves toward a procedural target, then a spring-damping model decides how it follows that target over time.

The target motion is generated from a mix of sine and cosine functions using the vertex's normalized position, the current time, motion speed, strength, direction, and randomness. That creates subtle spatial variation, so the image feels soft and lively rather than mechanically sliding as one flat piece.

The spring system gives the motion its character. A higher spring value makes vertices chase their target more eagerly. Damping controls how quickly motion loses energy. Strength determines the scale of the wobble, while clamping keeps offsets bounded so extreme settings do not tear the image apart.

The app also supports motion envelopes, including looping motion and settling motion. A settling envelope can start strong and decay over a short duration, which is useful for bounce-style effects that feel like a quick reaction instead of an endless loop.

Rendering with Three.js

Three.js is used as a focused rendering layer rather than a full 3D scene engine. The scene contains an orthographic camera and a single textured mesh. The orthographic camera maps the image coordinate system directly into the renderer, which makes it easier to align pointer input, mask sampling, and export dimensions.

Every animation frame follows a compact loop:

Update mesh physics based on elapsed time and motion settings.
Write the new vertex positions into the geometry buffer.
Render the scene to the WebGL canvas.

Because the renderer preserves the drawing buffer, the same canvas can be used for preview and export capture. That keeps exported media visually close to what the user sees in the editor.

Local Export: MP4 and GIF

Export is intentionally local. For MP4-capable browsers, the app uses HTMLCanvasElement.captureStream() with MediaRecorder. The renderer's canvas becomes a media stream, MediaRecorder collects video chunks, and the final Blob is downloaded directly by the browser.

GIF export follows a different path. The app captures frames from the rendered canvas, reads pixel data, quantizes colors with gifenc, writes frames into a GIF encoder, and returns a downloadable GIF Blob. This is more CPU-intensive than MediaRecorder, but it gives users a format that remains useful for stickers, posts, and lightweight sharing.

Both export paths report progress and support cancellation. That matters because media generation can take a few seconds, especially for longer animations or larger images.

Privacy as a Technical Feature

One of the most important design choices is that uploaded images stay local. The app does not need a server-side rendering pipeline to create the effect. Image decoding, mask editing, mesh deformation, preview rendering, and export all happen in the user's browser.

This is not only a privacy benefit; it also simplifies infrastructure. There is no upload queue, no storage lifecycle, no server-side image processing cost, and no need to retain user-generated artwork. For a creative tool where users may test personal drawings, avatars, fan art, or unreleased assets, that local-first model is part of the product experience.

Performance Lessons

The project highlights a few practical browser graphics lessons:

Dense meshes look smoother, but every extra vertex adds per-frame work. Mask sampling should happen when the mask changes, not every frame. Physics should use a stable delta time so animation does not explode after a tab pause or frame drop. Large images should be downscaled before editing so the tool remains fast on ordinary laptops.

The architecture also benefits from using the right rendering mode for each task. Canvas 2D is excellent for brush input and pixel masks. WebGL, through Three.js, is better for repeatedly drawing a textured deformable mesh. Keeping those jobs separate makes the app simpler and faster than forcing one API to do everything.

What Comes Next

Purupuru Maker's current architecture leaves room for richer creative controls. Future improvements could include more motion presets, undo and redo for mask edits, project save and restore, finer pinning or freeze masks, better mobile gestures, and additional export options through newer browser APIs such as WebCodecs.

The underlying pattern is flexible: a user-authored mask becomes weights, weights drive mesh motion, and the browser renders the result in real time. That pattern can support more than a jelly wobble. With different physics, presets, and masks, the same foundation could power breathing animations, subtle idle loops, heartbeat effects, shake reactions, and playful sticker motion.

Purupuru Maker shows how far modern browser APIs can go for small creative tools. With a focused architecture and a local-first pipeline, a static image can become an animated, shareable moment without leaving the page.

Building a Game Guide Site Without a Framework: The Quiet Power of Static HTML

天知道997 997 — Thu, 16 Jul 2026 07:51:37 +0000

I love a good framework as much as the next developer. Give me routing, components, hot reload, a tidy build pipeline, and I am happy.

But for this project, I deliberately went the other way.

Sootseer is a small, focused Palworld guide site. It answers a very specific player intent: where to find Sootseer, what it drops, how breeding works, and what changed in newer game data. It is not a dashboard. It is not a SaaS product. It is not a social app.

It is a content-first reference page.

So the architecture is almost aggressively simple:

Static HTML
One CSS file
One small JavaScript file
Local image assets
A privacy page
robots.txt
sitemap.xml
Structured data in the page head

No bundler. No hydration. No client-side router. No dependency graph that needs a weather report before deployment.

And honestly? It works really well.

The Main Technical Decision: Let HTML Do the Heavy Lifting

The page is built around plain semantic sections:

<section id="route">
  ...
</section>

<section id="breeding">
  ...
</section>

<section id="faq">
  ...
</section>

That sounds basic, but for a guide site, basic is a feature.

Search engines, browsers, screen readers, and impatient users all benefit when the document is readable before JavaScript does anything. The page has a real title, real headings, real links, real FAQ content, and real tables. If the JavaScript never runs, the core content still exists.

That was the rule I kept coming back to:

JavaScript can improve the experience, but it should not be required to understand the page.

For a game guide, this matters. A lot of visitors arrive from search with one narrow question. They do not want an app shell. They want the answer.

Structured Data Is Part of the Architecture

One thing I think developers often treat as “SEO garnish” is structured data. For this kind of site, I consider it part of the core architecture.

The page includes JSON-LD for:

Organization
WebSite
WebPage
Article
BreadcrumbList
FAQPage

That gives the content a machine-readable shape.

The visual page says, “Here is a Sootseer guide.”

The structured data says, more precisely, “This is an article, published by this entity, about this topic, with these FAQ answers, at this canonical URL.”

That distinction matters when the site is designed to compete in search results where many pages are saying roughly the same thing.

Just Enough JavaScript

The JavaScript layer is intentionally tiny. It handles three things:

Tab switching for encounter routes
Filtering the skill table
Remembering checklist progress in localStorage

The checklist is a nice example of progressive enhancement:

const storageKey = "sootseer-guide-checklist";

function readChecklist() {
  try {
    return JSON.parse(localStorage.getItem(storageKey)) || {};
  } catch {
    return {};
  }
}

Nothing here needs a framework. There is no shared global state problem. No server state. No complex synchronization. Just a few DOM nodes and a small piece of browser storage.

The page feels interactive, but the interaction is not allowed to take over the architecture.

CSS Carries the Product Feel

The CSS does more than make things pretty. It defines the whole reading experience.

The layout uses responsive grids, compact panels, sticky navigation, visual tags, loot cards, tables, and mobile-specific adjustments. The design goal was not “landing page.” It was “useful guide that feels polished.”

That distinction changed the UI choices.

Instead of a giant marketing hero and vague feature blocks, the first screen gives users the practical identity of the page: Sootseer, Palworld version context, type tags, stats, and direct navigation to location, Predator Core, breeding, and ranch information.

A content site can still have personality. It just has to respect the reader’s intent.

The Boring Files Matter

The project also includes robots.txt, sitemap.xml, Open Graph tags, Twitter card tags, canonical links, image preloading, and a privacy page.

None of that is glamorous.

All of it matters.

A small static site does not get to hide behind application complexity. Every file has a job. The page needs to load quickly, preview cleanly when shared, index correctly, and explain its data and privacy posture.

That is especially true for niche content sites. Trust is built through small signals: clear source policy, current review dates, stable URLs, and no unnecessary friction.

What I’d Use This Architecture For Again

I would happily reuse this approach for:

Game guide pages
Small documentation hubs
Local business microsites
Tool directories
Comparison pages
Static editorial projects
SEO-focused niche sites

I would not use it for everything. Once the site needs user accounts, server-side personalization, large content operations, or shared UI across hundreds of dynamic pages, I would reach for a framework.

But for a single-purpose guide, static architecture is not a compromise. It is a strategy.

The Lesson

Modern web development often nudges us toward more machinery than the problem actually needs.

This project was a useful reminder that a fast, useful website can still be made from the old ingredients: HTML that explains itself, CSS that respects the content, and JavaScript that knows when to stop.

Sometimes the best stack is the one that leaves the user alone and lets the page answer the question.

I Built a Daily Browser Game Without a Framework, and I Kind of Loved It

天知道997 997 — Thu, 16 Jul 2026 07:49:50 +0000

Modern web development can make you feel like every small idea needs a full production stack before it deserves to exist.

A framework. A router. A bundler. A component system. A styling strategy. A content layer. A deployment adapter. Maybe a database, because apparently we all enjoy having responsibilities.

For Vexle, a small daily flag-drawing game, I went in the opposite direction.

The site is built with plain JavaScript, a tiny Node.js static generator, JSON content files, one HTML game fragment, and a browser canvas. The final output is just a dist folder that can be dropped onto Vercel or any static host.

And honestly? For this kind of project, it felt great.

The Product Shape

Vexle is a daily geography game. The player sees a country name, draws the flag from memory, then reveals the real flag and gets a rough match score.

That meant the site needed a few things:

A playable first screen
Fast loading
Mobile-friendly drawing controls
Local daily progress
SEO pages like About, Privacy, and Terms
Metadata, Open Graph tags, structured data, sitemap, and robots.txt
A simple deployment story

What it did not need was a client-side app framework.

There is no complex state shared across routes. There is no authenticated dashboard. There are no deeply nested UI flows. The game is the app, and most of the surrounding site is content.

So the architecture became very boring in the best possible way.

The Architecture

The project is split into a few plain folders:


text
content/
  home.json
  game.html
  pages/
    about.json
    privacy.json
    terms.json

public/
  app.js
  styles.css
  data/
    game-data.json

scripts/
  build-static.mjs

server.mjs
site.config.json