picoCAD

A tiny modeller for tiny models. Twitter https://twitter.com/johanpeitz

Version 1.0.2 Discord https://discord.gg/hjXMammbPB
Itch https://johanpeitz.itch.io/picocad

Welcome to picoCAD!
picoCAD is a program to build and texture low poly 3D models. I needed something simple to
create simple models and found all other programs bloated and overly complicated, so I decided to
roll my own.

Since picoCAD is built with PICO-8 it comes with pretty harsh limitations. This is fine, since it
encourages the use of even less polygons. Be smart and creative and anything is possible!

Credits
Created by Johan Peitz, @JohanPeitz
3D math and fill routines adapted from Frederic Souchu, @FSouchu
Built on the PICO-8 platform created by Joseph White, @Lexaloffle

Overview
Use the following screens to get an overview of how to use picoCAD. But read on, there is a lot to
discover!
How to have a good time in picoCAD
3D in PICO-8 takes up a lot of the available performance. This means it will start running slow if the
models are too complex. Especially in build mode since the model has to be drawn four times.
Here’s some basic tips and tricks to stay sane.

● Plan ahead, decide on which volumes that will be needed early

● Don’t use too many primitives, extrude when possible
● Delete faces that won't be seen in the final export
● If you have multiples of something (e.g. wheels on a car), only build one and copy it when
everything else is done (including texturing it)
● Build simple stuff
Reference manual

Basic controls
Use mouse and keyboard to control all aspects of picoCAD. Using shortcut keys will greatly speed
up the workflow. In general:

Left mouse button Select vertices or faces

Hold X to select multiple

Left mouse button + move mouse Move whatever is selected

Right mouse button Bring up the context menu

Space Toggles 2x2 view or full view

Esc System menu (quit/windowed mode/etc)

ctrl/cmd+Z Undo last performed action

Mouse wheel Zoom in and out

Arrow keys Move whatever is selected

Arrow keys Move or spin the camera (when nothing is

selected)

For ease of use, most actions snap to a grid. This might feel cumbersome in the beginning but is of
great help to make things manageable at the low resolution.
File management
picoCAD stores your work in text files. These are easily readable and editable in case you want to
take your work elsewhere. Due to limitations in the pico8 platform, files will be stored in the
following location, regardless where you load them from.

Windows
%appdata%/Roaming/pico-8/appdata/picocad/
OSX
~/Library/Application Support/pico-8/appdata/picocad/
Linux
~/.lexaloffle/pico-8/appdata/picocad/

This folder can be opened via the “View files” option in the ☰ menu.

Also, beware that there is no warning before quitting or overwriting unsaved work, so save your
work often!

For file handling and exports to work properly, please make sure you are running the program with
administrator rights.

Loading projects
To load a previously saved picoCAD project, simply drag the txt file into the picoCad window.

Please note: picoCAD cannot remember where you loaded the project from, so when saved it will
end up in the same directory as everything else (see folders above).
Views
picoCad is structured around two views; build and texture. In the build view you place and
manipulate meshes, and in the texture view you can move around UV coordinates. Toggle between
the views with the top right buttons on the toolbar (or press V).

Both views support all three different render modes: wireframe, fill, and texture. Swap between

💡
them with the ▢ button. When in fill or texture mode, you can also toggle shading on or off with the
button.

Build view
The build view shows whatever you’re building from
three directions - one for each axis, and a fourth 3D
view. The general idea is that you build your model by
placing and manipulating meshes and vertices in the
three views, seeing the result in the 3D view. In each
viewport you can use the arrow keys to move the
camera around.

Press SPACE over the viewport you’re in to toggle

between full screen and 2x2. Working in full screen can
really help when your models become more complex.

Moving meshes
Grab a mesh with the left mouse button and drag it to
where you want it. This moves the mesh’s origin point as well which is important if you start
rotating things.

Selecting and moving vertices

Click vertices to select them. Select multiple vertices by holding down X. To select multiple vertices
in one go, draw a rectangle with the left mouse button and any vertices inside the rectangle will be
selected.

Hovering over faces takes precedence over selecting vertices so if you can’t reach a specific
vertex, hold X to force vertex selection.

Any selected vertices can then be moved by either dragging them directly with the mouse, or by
using the arrow keys. Moving vertices does not move the mesh’s origin point, which is important if
you later rotate the mesh.
Adding meshes
Click the [+] button to choose a volume to add. Right clicking almost anywhere also opens the
same menu. By using the available meshes creatively you should be able construct most things.

Mesh and face menu

Right click a face in a mesh to access additional mesh/face functionality.

Color mesh Set the color for the whole mesh used in fill mode.

Extrude face Extrude a face in the direction of it’s normal. For UV

coordinates of the new faces, picoCAD makes a best guess.
Adjust them in the texture view.

Rotate mesh Mesh is rotated around its center by 45 degrees. Use different
viewports to rotate around different axises.
You can also hover over a mesh and press R and T to rotate it.

Face props. Opens a submenu with face specific options.

Color Set the color for this face only.

Double sided Face will be visible from both sides.

No shading Face will not be shaded when

lighting is on.

No texture Face will use solid fill instead of

texture when in texture mode.

Draw behind Face will be drawn behind all other

faces.

Delete face Delete the highlighted face.

Delete mesh Deletes the whole mesh of the highlighted face.

Clone mesh Creates a copy of the current mesh and adds it to the scene.
Texturing view
This view is split between a 3D viewport and the texture.
Hover over faces in the model to see which part of the
texture it is using.

Manipulating UV coordinates
Click a face to be able to show it’s UV coordinates on
the texture. You can now drag the UVs to where you
want them. To quickly rotate the UVs of a face, hover
over it (or select it) and press R.

To use more of the texture than what is shown in the

window, scroll it with up and down arrows or the mouse
wheel.

Importing textures
Simply drag and drop a 128x128 PNG texture onto the program to use it for texturing (this cannot
be undone). Colors will be adjusted to fit the pico-8 palette, and the texture will be saved in the
project file.

Note that picoCAD needs some of the texture memory for internal use, so only the first 120 lines of
the texture will be used.

Bits and pieces

Background color
Use the palette button to choose the background color to use in the 3D viewport as well as which
color to treat as alpha in texture mode.

Mesh centre
Each mesh has a centre point, represented by a red dot when you hover over the mesh with the
mouse. When rotating the mesh, it will rotate around it’s centre. If you drag the mesh around, the
center point will follow. To move the center point, select all vertices and move them - they will then
be moved while the center point stays.

Project size cap

picoCAD is focused on small models and will restrict the data of your work to 16kB. An indicator
will show up at the bottom of the screen when you’re closing in on the cap.
Shortcuts and workflow tips
Speed up your workflow by using these shortcuts:

Select multiple vertices/UVs hold X and keep selecting

Select vertices inside meshes hold X and select

Disable snap to grid hold Z when selecting/moving

Swap render mode M

Toggle shading on/off L

Swap between build and texture views V

Rotate UVs select face + R

Export GIF rotating in opposite hold X when starting a GIF export

direction

Toggle fullscreen viewport fullscreen SPACE

Extrude face hover over a face + E

Rotate mesh hover over a mesh + R or T

Scale mesh hover over a mesh + Y or U

Show face property menu hover over a face + F

Save project cmd + S

Zooming mouse wheel up/down

Add a mesh right click on an orthogonal viewport

Reset zoom and pan double click build view button

Exporting to other formats
picoCAD comes with a program called “toolbox” which
allows you to export the picoCAD project files to various
other formats.

Launch the toolbox and drag and drop the project you want
to export onto the program. Once loaded, choose the export
option you want and the files will be created.

picoCAD is not able to export pngs with alpha, so some

post-editing may be needed on the texture.

Please note that files will be overwritten without prompting

so make sure you know what you’re doing.

Thanks
All the testers for helping me find gnarly bugs as well as ironing out the workflow (in no particular
order):
Antonio Menteguiaga, Pit, Waporwave, Jack Raymond, Jeiel Aranal, Khari Addison,
Preston Bruner, Miguel Sánchez, Annette Pew, Woolion, Chi Wong, Johan Vinet, Thomas
Leroy, errik, Riccardo Santangelo, and some who didn’t respond to whether they wanted
their names in here.

The PICO-8 community for being ever inspiring and supportive.

Version history
v1.0.2
● picoCAD
○ Added ability to scale mesh (Y/U)
○ Added ability to disable snap when editing UVs (hold Z)
○ Added easter egg
○ Renamed “Render 1st” to “Draw Behind”
○ Tweaked spin speed in 3D view to be a bit slower
○ Removed window title
○ Removed inability to show primitive menu in 3D view
○ Fixed model being wiped on undo when memory consumption has emptied undo
buffer
○ Fixed shading thresholds for color and texture not matching
○ Fixed dithered shading not lining up between textured and colored faces
○ Fixed pause menu appearing on some systems on pressing enter when saving a
project under new name
○ Fixed files sometimes not accepted when dragged onto the application
● toolbox
○ Fixed exported OBJs being mirrored
○ Fixed trying to load non picoCAD projects leading to a crash

v1.0.1
● picoCAD
○ Added ability to disable snap to grid when moving vertices and meshes (for real this
time)
○ Added title to window
○ Changed GIF save name to use project name (eg banana_0.gif)
○ Removed outdated reference to desktop when saving gif
○ Removed p8l export from main application
○ Fixed model being wiped when reaching end of undo buffer
○ Fixed faces occasionally being highlighted during gif export
○ Fixed rotation via menu rotating around the wrong axis in some cases
● toolbox
○ Added functionality to export obj, mtl, png
○ Added functionality to export p8l
○ Added functionality to export png

v1.0
● Added ability to to disable snap to grid when moving vertices and meshes (hold Z)
● Tweaked spin speed in model view to be a bit faster
● Fixed crash when attempting to save with empty filename
 ● Fixed some actions not creating undo states
● Fixed textures not loading properly if only colors 0-9 where used

v0.9.13 - RC4
● Tweaked spin speed in model view to be a bit slower
● Tweaked toast messaged to stay on screen a bit longer
● Removed the * next to filename that was displayed if unsaved changes
● Fixed normals getting funky when merging vertices (and other special cases)

v0.9.12 - RC3
● Added a dithered shading step for textures
● Removed ability to save empty scenes.
● Tweaked the size and position of some ui elements
● Tweaked the colors used for the GIF watermark
● Fixed rectangle select not working in model viewport
● Fixed mesh center points not being drawn unless in wireframe mode
● Fixed color and zoom settings in project file being ignored
● Fixed project colors not being set correctly in some circumstances
● Fixed double sided planes flashing during some circumstances

v0.9.11 - RC2
● Added a [+] button for simple mesh adding
● Tweaked position of version string on about screen
● Fixed color menu not showing if clicking too far to the right on a menu option
● Fixed filename being displayed on top of save as prompt
● Fixed meshes not being draggable in ortographic viewports unless in wireframe mode

v0.9.10 - RC1
● Changed positions of most UI elements
● Removed ability to change render mode in orto views
● Fixed config issue causing slow spinning gifs to cut short
● Fixed gif menu showing up when clicking on a specific place
● Fixed gif export being choppy if scene suffered from low framerate
● Fixed vertices getting unselected when changing render mode
● Fixed project size not being recalculated on undo

v0.9.9
● Added a cap on how much content can be put into a single scene (16kB)
● Added toast message when hitting content cap
● Added a visual cue when approaching content cap
● Added different spinning speeds when exporting GIF
● Added functionality to rotate GIF in opposite direction (hold X when selecting in menu)
 ● Added ability to reset all views to default by clicking build view icon when already in build
view
● Removed zoom reset button (1:1)
● Removed 1px border being applied to all viewports
● Changed position of #picoCAD watermark not to collide with GIF tag on Twitter
● Changed colors on message toast
● Changed looks and content on About screen
● Fixed undo buffer from being wiped if running out of memory
● Fixed texture not being reset when starting new project
● Fixed filename input not allowing numbers
● Fixed being able to scroll texture too far
● Fixed viewports ending up in a funky state when importing a project while in texture view

v0.9.8
● Added shortcut to face property menu (press F while hovering a face)
● Added #picoCAD tag when exporting gif
● Removed menu borders when exporting gif
● Removed zoom percentage indicator
● Removed limit when zooming out
● Removed WASD mapping as is clashed with other keys and had different mapping on
different systems
● Removed ! indicator (cpu>100%)
● Changed so that GIF export saves in the same directory as everything else
● Changed menu option from OPEN to VIEW FILES
● Fixed zoom levels not being set properly on loading a model
● Fixed not being able to scroll texture with mouse wheel if a vertex was selected
● Fixed shading being inverted on the back of double sided faces
● Fixed crash caused by rotating a texture when no face was selected
● Fixed crash caused by loading files too big (>32k-ish)
● Fixed faces passing through the camera from being rendered twisted
● Fixed views not resetting properly when starting a new project

v0.9.7
● Added ability to start new project from menu
● Added ability to open folder where picoCAD saves everything
● Added ability to scroll the texture with mouse wheel
● Added ability to use WASD as well as arrow keys
● Added window mode to be default on first launch
● Added hovered UVs on textures being highlighted in the model viewport
● Added ability to select vertices inside meshes buy holding down X
● Added plane primitive
● Reversed mouse wheel scroll direction
● Adjusted perspectiveness to be less extreme
 ● Adjusted vertex selection to standard interaction models
● Fixed non-shaded textures not handling transparency correctly when lit
● Fixed top left 8x8 of texture not being usable
● Fixed cameras moving when entering filenames
● Fixed UV selection getting messed up when rotating UVs
● Fixed files being written to obscure pico8 path instead of sane location, new locations:
○ Windows: %AppData%/Roaming/pico-8/appdata/picocad/
○ OSX: /Users/Yourname/Library/Application Support/pico-8/appdata/picocad/
○ Linux: ~/.lexaloffle/pico-8/appdata/picocad/

v0.9.6
● Rolled back save fix, files are now saved as before (in mystery folder)
● Added minimum and maximum to zoom levels
● Added near camera clipping
● Added mouse wheel zoom
● Adjusted lighting settings
● Adjusted the rotation speed when recording gifs to be 10% faster
● Fixed 3D view not using perspective projection
● Fixed unlimited undo buffer leading to out of memory crash
● Fixed normals not being recalculated when dragging vertices
● Fixed crash caused by zooming in until division by zero occurred
● Fixed distorted frames appearing when recording gif of heavy models
● Fixed visibility check sometimes being a bit off
● Fixed crash caused by selecting “-------” from the menu

v0.9.5
● Added display of mesh origio when hovering a mesh in wireframe mode
● Added ability to rotate meshes in both directions using R & T keys
● Changed direction of movement when moving the camera with the arrow keys in an
orthogonal viewport
● Changed cylinder primitive to be on grid
● Change pentagonal prism primitive to center around it’s origo
● Adjusted light source to be slightly more from above
● Adjusted mouse and vertex interaction to be more forgiving
● Adjusted shading angles when using textures
● Fixed files being written to obscure pico8 path instead of program root
● Fixed color selection menu not resetting properly, causing the wrong things to be colored
● Fixed crash caused by changing render mode with the M key while hovering a face

v0.9.4
● Optimised vertex pipeline for slight (10%) performance increase
● Fixed viewports getting out of sync when moving camera in full screen
● Fixed view buttons creating strange states when pressed repeatedly
 ● Fixed texture coordinates getting messed up if texture was scrolled all the way down
● Fixed undo state not being created when changing face properties
● Fixed undo state not being created when cloning a mesh
● Fixed crash caused when menu was opened in the model view but selected over the
texture

v0.9.3
● Added individual face properties (back-face rendering, ignore shading, ignore texture, color,
render order) for faces and access via menu
● Added graceful error fallback on trying to import a non-picoCAD project
● Fixed so that the full version number is visible on the credits screen
● Fixed UV rotations not being stored in the project properly
● Fixed the build menu being accessible from texturing view
● Fixed deleting mesh not creating an undo state
● Fixed p8l export concatenating data instead of creating a new file
● Fixed hovering a face before entering the texture map conflicting with the selected face
● Fixed model from rotating when scrolling the texture
● Fixed uvs from not being selected if texture is scrolled

v0.9.2
● Added ability to scroll in texture view to use full texture
● Added a default texture
● Added ability to rotate face UVs
● Adjusted shading palette for pink and peach
● Adjusted model spinning speed when exporting to GIF
● Removed ability to rotate meshes in 3D viewports
● Fixed some primitives not spawning face up
● Fixed default UVs for all primitives
● Fixed so that texture doesn’t scroll when rotating model in texturing view

v0.9.1
● Fixed texture being 1px offset when reading from txt file
● Fixed compatibility issues in txt file between mac and pc
● Fixed crash when right-clicking selected vertices
● Fixed crash when undoing into an empty scene

v0.9
● First beta release