zdog README

The project's README from github.com/metafizzy/zdog. As one markdown file: README.md.

Zdog

Round, flat, designer-friendly pseudo-3D engine

View complete documentation and live demos at zzz.dog.

Install

Download

CDN

Link directly to Zdog JS on unpkg.

<script src="https://unpkg.com/zdog@1/dist/zdog.dist.min.js"></script>

Package managers

npm: npm install zdog

Bower: bower install zdog

Hello world demo

Create 3D models with Zdog by adding shapes. See Getting started for a walk-through of this demo.

let isSpinning = true;

let illo = new Zdog.Illustration({
  element: '.zdog-canvas',
  zoom: 4,
  dragRotate: true,
  // stop spinning when drag starts
  onDragStart: function() {
    isSpinning = false;
  },
});

// circle
new Zdog.Ellipse({
  addTo: illo,
  diameter: 20,
  translate: { z: 10 },
  stroke: 5,
  color: '#636',
});

// square
new Zdog.Rect({
  addTo: illo,
  width: 20,
  height: 20,
  translate: { z: -10 },
  stroke: 3,
  color: '#E62',
  fill: true,
});

function animate() {
  illo.rotate.y += isSpinning ? 0.03 : 0;
  illo.updateRenderGraph();
  requestAnimationFrame( animate );
}
animate();

About Zdog

Hi, Dave here. I wanted to make a video game. I needed a 3D engine, but most engines were too powerful and complex for me. I made Zdog so I could design and display simple 3D models without a lot of overhead.

Zdog is directly inspired by Dogz, a virtual pet game by P.F. Magic released in 1995. It used flat 2D circle sprites to render the Dogz’ models, but in a 3D scene. See Dogz playthrough video here. Dogz were fully animated in real time, running, flopping, scratching (on Windows 3.1!). It was remarkable.

Zdog uses the same principle. It renders all shapes using the 2D drawing APIs in either <canvas> or <svg>. Spheres are actually dots. Toruses are actually circles. Capsules are actually thick lines. It’s a simple, but effective trick. The underlying 3D math comes from Rotating 3D Shapes by Peter Collingridge.

Zdog is pronounced "Zee-dog" in American parlance or "Zed-dog" in British.

Beta!

Zdog v1 is a beta-release, of sorts. This is my first time creating a 3D engine, so I probably got some stuff wrong. Expect lots of changes for v2. Provide input and select new features on the Zdog issue tracker on GitHub.

More Zdog resources

Other people's stuff:

My stuff:


Licensed MIT. Made by Metafizzy 🌈🐻

zdog (metafizzy/zdog)

2d
Searching Database…

10.7K ·GitHub
What is this?Zdog is a round, flat, designer-friendly pseudo-3D engine for the web: you build 3D models in JavaScript by adding shapes, and it renders them with 2D drawing APIs to canvas or SVG.
Is it a real 3D engine, or what does the 'pseudo-3D' part mean?It is a trick: Zdog draws flat 2D shapes placed in 3D space — spheres are actually dots, toruses are circles, capsules are thick lines. The rotation math is real 3D, only the rendering is flat, the same principle as the 1995 game Dogz that inspired it.
How do I add it to a page?Install with npm install zdog (Bower works too), link zdog.dist.min.js from the unpkg CDN, or download the file directly. Documentation and live demos live at zzz.dog.
Does it need any other libraries or a build step?No. It ships as a plain JavaScript file with zero runtime dependencies, so a script tag or one npm install is all it takes.
Is it stable, or still changing?Treat it as beta: the author calls v1 'a beta-release, of sorts' and says to expect lots of changes for v2, so APIs may shift.
Why did the author build this instead of using an existing 3D engine?Dave of Metafizzy wanted to make a video game but found real engines too powerful and complex, so he built Zdog to design and display simple 3D models without a lot of overhead. It is directly inspired by Dogz, a 1995 virtual pet game.
How do you build a model with it?You create models in code by adding shapes — spheres, toruses, capsules and the like — to a scene. The Getting started guide on zzz.dog walks through a full hello-world demo.
Is there an ecosystem around it?Yes: Zfont is a text plugin, vue-zdog is a Vue wrapper, zDogPy is a Python port for DrawBot, plus Made with Zdog CodePen and Twitter collections for inspiration.
How do you pronounce Zdog?'Zee-dog' in American parlance or 'Zed-dog' in British.
Creator
metafizzy
Size
0.6 MB
Stars
10.7K
Age
7y
Commits · 90 Days