Files
2026-11-02 19:38:04 +01:00

666 lines
37 KiB
GDScript
Executable File

@tool
class_name PdDocs
## In-plugin documentation: a resizable window with a section list on the
## left and the full user guide on the right. Covers every button, tool,
## menu, mode and workflow of the plugin, with how-tos and use cases.
const ACCENT := "4da3ff"
# ------------------------------------------------------------- links -----
# Public pages opened in the OS browser: from the docs window's top line
# and from the links row at the top of the Welcome page.
const URL_PLUGIN := "https://choco-ted.itch.io/polydoodle"
const URL_RATE := "https://choco-ted.itch.io/polydoodle/rate?source=game"
const URL_OTHER := "https://choco-ted.itch.io/"
const SECTIONS := [
["Welcome", "welcome"],
["The Two Workspaces", "workspaces"],
["Toolbar Reference", "toolbar"],
["Object Mode", "mode_object"],
["Vertex / Edge / Face Modes", "mode_elements"],
["Draw Mode", "mode_draw"],
["Gizmos: Move, Scale & Rotate", "gizmos"],
["Grid, Snapping & Views", "views"],
["Hierarchy Panel", "hierarchy"],
["Texture Editor: Painting", "paint"],
["Brush, Fill & Pixel Tools", "paint_tools"],
["Smooth & Pixel Filter Modes", "filter"],
["Texture Resolution", "resolution"],
["Import Images (Stickers)", "stickers"],
["Texture Editor: Edit UV", "uv"],
["Rotate & Scale UVs", "rotate"],
["Undo, Save & Open", "files"],
["Import 3D Models", "import3d"],
["Export for Godot", "export"],
["Keyboard & Mouse Map", "keys"],
["Use Cases & Workflows", "usecases"],
["Troubleshooting", "trouble"],
]
const BODY := """
[h2]Welcome to Polydoodle[/h2]
[b]Enjoying Polydoodle?[/b] [color=#4da3ff][url=[[RATE]]]★ Rate this plugin[/url][/color] · [color=#4da3ff][url=[[PLUGIN]]]Plugin page[/url][/color] · [color=#4da3ff][url=[[OTHER]]]My other works[/url][/color]
Polydoodle is a cute little poly modeler that lives inside the Godot
editor. It gives you two connected workspaces: a [b]3D modeler[/b] for
building low-poly shapes from primitives, freehand doodles and per-element
editing, and a [b]texture editor[/b] for painting textures and editing UVs
on those shapes. Everything you make can be exported straight into Godot
as a mesh, a scene, an OBJ (with its texture), or dropped into the current
scene.
[color=#4da3ff]Use case:[/color] model a low-poly dungeon prop, paint its
texture in the same editor, and export it - without ever leaving Godot.
[h2]The Two Workspaces[/h2]
The [b]first toolbar button[/b] is a joined pair: [b]3D Editor[/b] |
[b]Texture Editor[/b] (or press [b]6[/b]). Exactly one half is active.
[color=#4da3ff]3D Editor[/color] - the classic quad view (Top / Perspective /
Side / Front) with all modeling tools: selection modes, drawing, gizmos,
mesh context menus, the hierarchy and the properties panel.
[color=#4da3ff]Texture Editor[/color] - the 3D viewport moves to the top and
the [b]texture canvas[/b] takes the lower half. The top toolbar swaps the
modeling buttons for the texture tools (Paint | Edit UV, brush, fill,
pixel, import, snap, rotate, detach) - sliders and deeper settings live in
the right panel. The modeling buttons come back when you return to the 3D
editor.
[h2]Toolbar Reference[/h2]
[color=#4da3ff]Workspace pair[/color] - switch between the 3D editor and the
texture editor (key 6).
[color=#4da3ff]Object / Vertex / Edge / Face[/color] - the four selection
modes (keys 1-4). Their buttons are exclusive: exactly one is active.
[color=#4da3ff]Draw[/color] - a split button: the main half enters Draw mode
(key 5) with the current shape; the small arrow half opens the shape menu
(Freehand, Rectangle, Circle, Triangle, Pentagon, Hexagon, Star, Torus).
The main icon always shows the current shape.
[color=#4da3ff]Move | Scale | Rotate Gizmo[/color] - the gizmo buttons show
the move arrows, the scale handles or the rotation rings on the selection.
The active one is pressed; click it again to hide the gizmo. In the 3D
workspace the keys [b]G / S / R[/b] pick the Move / Scale / Rotate gizmo
(pressing the active one's key hides it again).
[color=#4da3ff]Snap / Grid / Both Sides[/color] - grid snapping on/off (T,
off by default), grid visibility (V), and rendering both sides of every
face without backface culling (B, on by default).
[color=#4da3ff]Add[/color] - the FIRST button of the toolbar group, right after
the workspace switch. Insert a primitive: Cube, Plane, Cylinder,
Sphere, Prism or Torus.
[color=#4da3ff]Duplicate / Delete[/color] - duplicate the selection
(Ctrl+D) or delete it (Del).
[color=#4da3ff]Undo / Redo[/color] - step history back or forward
(Ctrl+Z / Ctrl+Shift+Z).
[color=#4da3ff]Save / Open[/color] - write or load a .pdoodle project file.
[color=#4da3ff]Import Model[/color] - bring in an existing 3D model (OBJ, glTF /
GLB, FBX) together with its textures.
[color=#4da3ff]Export[/color] - Mesh (.tres), Scene (.tscn), OBJ
(+ .mtl + texture PNG), or add the model to the current scene.
[color=#4da3ff]Background color[/color] - the color swatch on the right
tints all viewports.
[color=#4da3ff]Gear[/color] - editor settings: 3D shading mode (Shaded + Wire,
Shaded, Wireframe), grid visibility, the [b]Contextual Hints[/b] toggle
that shows or hides the in-viewport tip lines, and the [b]Checkerboard[/b]
section: [b]Show Checkerboard[/b] (hide it and every unpainted texel is
fully transparent in all views - and exports transparent) and
[b]Bake Into Export[/b] (force the checkerboard into every exported texture
so nothing is transparent). The popup opens on the
right, right-aligned under the gear, and always stays inside the plugin
area.
[color=#4da3ff]Book[/color] - this documentation.
[h2]Object Mode (1)[/h2]
Click a shape to select it. [b]Shift+Click[/b] adds to the selection,
clicking an already-selected object keeps the whole multi-selection so a
drag moves every part together. Drag empty space in a 2D view to
box-select. Drag the selection (or use the gizmo) to move it. In the 3D
view, dragging empty space orbits and a plain click on empty space
deselects. [b]Ctrl+drag[/b] rectangle-selects several objects at once.
Right-click opens the object menu (Duplicate, Delete, Select All,
Deselect) in the 3D view AND in every 2D view. The right panel edits the
selected object's name, position and scale numerically.
[color=#4da3ff]Use case:[/color] lay out a whole scene of props, then
multi-select and move them as one group.
[h2]Vertex / Edge / Face Modes (2-4)[/h2]
These edit the active object's elements. Click a vertex, edge or face to
select it (Shift adds, clicking a selected one removes it), then drag to
move it. Drag empty space in 2D views to box-select; in the 3D view
[b]Ctrl+drag[/b] rectangle-selects. Right-click in the 3D view OR any 2D
view offers the mesh operations of the mode:
[b]Vertex:[/b] Merge Vertices (weld to the centroid), Delete, Select All.
[b]Edge:[/b] Extrude Edges (push fins out of the selected edges), Delete.
[b]Face:[/b] with several faces selected the menu offers BOTH extrude
modes - [b]Extrude Faces (Individual)[/b] pushes every face along its
own normal, [b]Extrude Faces (Combined)[/b] moves the whole selection
as ONE region: edges shared between selected faces get no wall and the
sheet lifts along the average normal, exactly like a single face. The
selected faces MOVE in both: side walls connect the old boundary to the
moved copy which becomes the selection (drag it to keep extruding; no
leftover face stays behind at the old spot), [b]Inset Face(s)[/b] /
[b]Outset Face(s)[/b] - the face's vertex ring moves toward (or away
from) the face center in its own plane: one coplanar quad strip per
original edge plus the smaller / larger inner face, the surface stays
closed and NOTHING overlaps (no duplicate faces; new faces inherit the
face's color; the depth comes from the right panel's Inset slider),
Fill Face(s) with the current paint color, Clear Face Paint, Delete.
[color=#4da3ff]Use case:[/color] select the top face of a cube and extrude it
twice for a tower; select its four side vertices and merge them into a
pyramid tip.
[h2]Draw Mode (5)[/h2]
Pick a shape from the Draw split button, then drag in ANY viewport:
[list][*][b]Freehand[/b] - sketch a closed loop; it becomes a "Doodle"
polygon face (self-crossing loops are triangulated robustly).
[*][b]Rectangle[/b] - drags a true rectangle.
[*][b]Circle[/b] - drags an ellipse (Shift = circle).
[*][b]Triangle / Pentagon / Hexagon / Star[/b] - regular n-gons fitted to
the drag rect (Shift = square rect).
[*][b]Torus[/b] - drags a full 3D torus; the drag defines the outer
radius and the ring sits on the surface or plane under the cursor.[/list]
In the 3D viewport the shape is drawn on the face under the cursor (or a
horizontal plane through the selection) - draw straight onto walls and
floors. The preview outline follows the drag; release to create. Every
shape lands as a normal editable object.
[color=#4da3ff]Use case:[/color] draw a star flat on the ground, extrude its
face, and you have a badge; draw a torus on the floor for a ring gate.
[h2]Gizmos: Move, Scale & Rotate[/h2]
The gizmo buttons show handles on the current selection's center. The
gizmo only appears when something is actually selected: a shape in Object
mode, or vertices / edges / faces in the element modes. With nothing
selected, turning a gizmo on shows a notice telling you what to select.
[b]Move gizmo:[/b] drag an axis arrow to slide the selection along that
world axis; drag near the center chip for direct element dragging.
[b]Scale gizmo:[/b] the axis tips are little cubes - drag one to scale
that single axis; the [b]center cube[/b] scales the selection uniformly.
Scale factor 1.0 is the untouched size; snapping quantizes to 0.05 steps
when enabled. The scale gizmo works on whole objects AND on selected
vertices/edges/faces (it scales their positions around the selection
center). Direct dragging without the gizmo always works too.
[b]Rotate gizmo:[/b] drag a ring to spin the selection around that axis
(15-degree steps while snapping is on). In the 3D view there is one ring
per world axis; in the Top/Front/Side 2D views there is a single ring
around the view's own axis, and the object always turns the same way
your cursor does. Rotating always edits actual vertex positions around
the selection center.
[color=#4da3ff]Use case:[/color] select a wall, switch to the scale gizmo, and
drag the Y cube to change its height without touching the plan size; or
spin a prop 45 degrees on the ground plane with the rotate ring.
[h2]Shading: Flat or Smooth (per object)[/h2]
Every object carries its own shading flag. The [b]Shading[/b] row
([b]Flat | Smooth[/b]) lives in the right panel's Object group, and each
hierarchy row shows a small toggle for it too. [b]Flat[/b] (default)
keeps the hard faceted low-poly look - every face shades with its own
normal. [b]Smooth[/b] averages the normals wherever faces share a
vertex, so rounded shapes (spheres, cylinders, tori) shade continuously.
The flag is undoable, saved in project files, and exported: .tres/.tscn
meshes carry the smooth normals and OBJ exports write s on / s off per
object.
[h2]Grid, Snapping & Views[/h2]
[b]Snap (S)[/b] lands moves, shapes, gizmo drags and scale factors on the
grid. The grid step is the plugin's world unit. [b]Grid (V)[/b] hides the
grid lines but snapping keeps working. Every viewport has corner buttons:
the 2D views (Top/Front/Side) have a [b]flip button[/b] showing the
opposite view (Bottom/Back/Left) - picking and painting follow the flip
automatically - and EVERY viewport (all four 3D-modeler views, the texture
editor's 3D viewport and the texture canvas) has an [b]expand button[/b]
(two outward arrows) right next to it: press it and that viewport alone
fills the whole view area, press it again (or Space) to retract to the
previous layout. Space still expands the focused view. Wheel zooms,
right-drag pans, middle-drag (or Alt+drag) orbits the 3D view. The gear
menu sets the 3D shading: Shaded + Wire, Shaded, or Wireframe.
The three 2D views render the model with the SAME texture the 3D
viewport samples: an unpainted model shows the checkerboard placeholder
in every view, painted texels show through everywhere, so Top/Front/Side
always match what the model actually looks like.
[b]Contextual hints[/b] - every viewport shows a small muted hint line at
its bottom edge that adapts to what you are doing: select a face and it
says "Right-click: options (EXTRUDE faces, fill, delete and more)", start
placing an image and the canvas says "Scroll: adjust scale · Right-click:
rotate · Click: place · Esc: cancel". The editor teaches itself - no
manual required. Prefer a clean viewport? Switch the hints off in the
gear menu (Editor Settings > Viewport > Contextual Hints).
The three 2D views render by PHYSICAL depth, not by hierarchy order:
whatever is genuinely in front in 3D space paints last in every ortho
view (and two interpenetrating objects interleave per face). Selection
outlines, vertex handles and the gizmo always draw above the scene.
[h2]Hierarchy Panel[/h2]
The upper right panel lists every object with its vertex count. Click to
select it - the 3D view selects the object and shows the gizmo.
[b]Ctrl+click[/b] toggles rows on and off, [b]Shift+click[/b] selects a
range - multi-selecting rows works exactly like the viewport, and every
multi-selection made in a viewport shows as multiple highlighted rows
here. Double-click (or click again) the name to rename. The [b]eye[/b]
hides/shows an object (hiding auto-locks it so it can never be picked by
accident; the auto-lock releases when you show it again). The
[b]padlock[/b] manually locks/unlocks an object: locked objects render
but ignore picking, editing and painting.
The five [b]stars[/b] next to the Hierarchy title are the rating shortcut:
if Polydoodle makes your days easier, click them - it opens the plugin's
rating page, and it genuinely helps.
[h2]Texture Editor: Painting[/h2]
Press the workspace pair's [b]Texture Editor[/b] half. The toolbar now
shows the texture tools (Brush, Fill, Fill Object, Pixel, Eraser,
Picker, Replace, Import Image); the right panel shows paint color, the
palette, recent colors, resolution, filter mode and tool sizes.
The lower canvas is the object's [b]texture atlas[/b]: every face owns
one rectangular island outlined on it. The atlas starts EMPTY - the
checkerboard you see is a generated placeholder shown UNDER the page,
and the page itself is fully transparent until you paint: paint lands
only where you put it and everything else stays see-through, with the
checker and the texel grid visible underneath. What you paint on the
canvas IS what renders on the 3D model (unpainted texels show the
placeholder there too), and painting directly on the 3D model lands on
the same texels. The brush ring (or the pixel square) follows
the cursor in BOTH the 3D viewport and the canvas. Clicking a face on
the 3D model or an island on the canvas also selects that face, so you
always know which island you are on.
[color=#4da3ff]Transparency workflow[/color] - the gear menu's [b]Show
Checkerboard[/b] switch decides what unpainted texels look like: keep it
ON for the classic checker placeholder, or switch it OFF and every
unpainted texel becomes FULLY TRANSPARENT in the 3D view, the 2D views
and the canvas (the see-through preview of a transparent export). The
[b]Bake Into Export[/b] switch next to it forces the checkerboard into
every exported texture (mesh, scene, OBJ PNGs) so the exported result is
NEVER transparent where nothing was painted - handy for exports that
should keep the playful placeholder look. With both switches off, an
exported model keeps real alpha-0 holes where nothing was painted, and
Render Both Sides keeps every surface two-sided.
[color=#4da3ff]Use case:[/color] paint eyes onto a character's head island
while watching the 3D model update live.
[h2]Brush, Fill & Pixel Tools[/h2]
[color=#4da3ff]Brush[/color] - paints a round stamp whose size (world units)
is set by the Brush size slider. Strokes are texel-precise: they follow
the surface exactly, across face borders, on the model or the canvas.
[color=#4da3ff]Fill[/color] - repaints EXACTLY the clicked face's island,
edge to edge, at its CURRENT UV position (moved islands are repainted
where they render now, not at their default spot). Never spreads to
neighbors. Fills bleed a couple of texels past the island edge so no gap
can appear between the paint and the face border.
[color=#4da3ff]Fill Object[/color] - repaints every island of the object at
once.
[color=#4da3ff]Pixel[/color] - the [b]texel-perfect[/b] pixel-art brush: it
paints exact N x N texel blocks aligned to the atlas grid (the Pixel
size slider is in TEXELS - 1 paints single texels), with texel lines
joining fast strokes so nothing gaps. Pair it with the PIXEL filter mode
for crisp results. There is no anti-aliasing and no fake half-texels:
what you see is exactly what is painted.
[color=#4da3ff]Eraser[/color] - brush strokes that restore transparency
(the unpainted look: the checker placeholder shows through again). Works on the model AND the canvas; the ring cursor
shows the erase footprint. It uses the EXACT same size, opacity, edge
smoothness and face-lock settings as the Brush. Right-click does not
erase - erasing belongs to the dedicated Eraser tool.
[color=#4da3ff]Opacity & Edge smoothness[/color] - the right panel's sliders
(Brush or Eraser active). [b]Opacity[/b] is the stamp strength: 100%
paints solid, lower values blend see-through strokes that build up along
the path. [b]Edge smoothness[/b] is the airbrush falloff: 0 keeps a hard
circle edge, 1 sprays a fully soft airbrush stamp - perfect for shading
blush, gradients and smoke.
[color=#4da3ff]Face lock[/color] - the padlock toggle in the right panel (Brush,
Eraser or Pixel active). When ON, a stroke stays inside the face it
STARTED on - in the 2D canvas AND on the 3D model. Like the fill system,
the paint reaches slightly past the face's own edges (the same bleed
margin the Fill tool uses) so its borders are fully covered, but it never
paints any other face or any further into empty canvas. The status line
confirms the lock when a locked stroke starts.
[color=#4da3ff]Picker[/color] - the eyedropper: click any texel on the
model or the canvas and its color becomes the paint color (added to the
Recent row). Drag it around to sample continuously. Not an undo step.
[color=#4da3ff]Replace[/color] - click a texel: every texel of THAT color
inside the clicked island is swapped for the current paint color (a
couple of bleed texels included, never crossing into other islands).
Clicking an unpainted (transparent) texel recolors the island's whole
unpainted area. Undoable - a drag across several islands undoes as one
sweep.
[h[color=#4da3ff]Replace[/color] - click a texel and every texel of that
color on the WHOLE canvas (all faces) becomes the paint color. The
[color=#4da3ff]Tolerance[/color] slider (right panel, shown while the
tool is active) widens the match: 0% replaces only the exact color,
higher values also replace nearby shades - handy for swapping a hand-
painted gradient. One undo step returns the whole swap.
[h2]Smooth & Pixel Filter Modes[/h2]
The right panel's Filter buttons switch how the texture is sampled:
[b]Smooth[/b] - the texture is linearly filtered: soft, anti-aliased
look on the model AND in the editor. Best with the normal Brush.
[b]Pixel[/b] - filtering is OFF on the model AND the editor canvas:
texels render razor sharp for pixel art. The pixel brush is the natural
tool here (switching modes auto-swaps the default tool).
[color=#4da3ff]Use case:[/color] paint a 32x32 pixel-art skin in Pixel mode,
then flip to Smooth to preview how it reads with filtering.
[h2]Texture Resolution[/h2]
The Resolution dropdown (right panel, Texture group) changes the active
object's atlas to 64/128/256/512/1024 per side - or pick [b]Custom...[/b]
and type any size between 16 and 1024 texels per side (slider or number
entry) for non-standard targets like 300 x 300. The paint is resampled
(nearest), islands, texel density and UV offsets all scale by the same
factor, so every stroke stays exactly where it was - just sharper or
softer. The change is undoable and is saved in project files. A warning:
islands that no longer fit are re-packed automatically; when the model
is very complex the editor may also grow the atlas on its own.
[h2]Import Images (Stickers)[/h2]
The [b]Import Image[/b] button (Paint submode) opens a file dialog. The
picture then floats on the canvas as a ghost:
[list][*]Move the mouse - the ghost follows.
[*][b]Wheel[/b] - scales it bigger/smaller.
[*][b]Right-click[/b] - rotates it 90 degrees.
[*][b]Click[/b] - places it (alpha-blended into the atlas, undoable).
[*][b]Esc[/b] - cancels.[/list]
Afterwards the placed image is just texels: paint over it, erase parts,
fill it. Oversized imports are auto-fit into the atlas.
[color=#4da3ff]Use case:[/color] import a logo, scale it with the wheel,
rotate it upright with right-click, place it on a crate's side island,
then rough it up with the eraser.
[h2]Texture Editor: Edit UV[/h2]
The [b]Edit UV[/b] toolbar button switches the texture editor to UV
editing - the right panel swaps its paint controls for the UV toolset
(selection mode, snapping, island actions, the Rotate / Scale sliders).
Clicking a face on the 3D model selects it and highlights its island on
the canvas (and the other way around).
[b]Select mode[/b] (right panel) decides what clicks and the rectangular
selection grab: [b]Vertex[/b], [b]Edge[/b] or [b]Face[/b]. Selection
rules in every mode:
[list][*]A plain click selects ONE element (replacing the selection).
[*][b]Ctrl or Shift + click[/b] adds an element to the selection.
[*]Grabbing an element that is part of the selection moves the WHOLE
selection - box-select corners, then drag any one of them.
[*]A bare click on empty canvas deselects everything.
[*]An empty-space DRAG box-selects the active element type.[/list]
[b]Snap[/b] (toolbar) makes UV drags land PIXEL-PERFECT on the texel
grid: with snapping on, the dragged corners land exactly on texel
boundaries, so the island outline aligns edge to edge with the atlas
pixels (even for islands whose corners sit at fractional texel positions
after vertex edits). Hold Ctrl to drag sub-texel freely.
[b]Right-click[/b] the canvas for the mesh menu: Rotate UV 90° CW / CCW,
Detach Selected Face(s), Merge Vertices, Extrude Face / Edges, Fill /
Clear, Delete Face(s)/Edge(s)/Vertex(es), Select All Islands, Deselect,
Reset UVs. [b]Detach[/b] moves the selected islands to free atlas space
so they can be laid out individually. The HUD line shows the mode, atlas
size and zoom.
[h2]Rotate & Scale UVs[/h2]
Two toolbar toggles (Edit UV submode) transform the selected faces' UVs
around the selection's center; exactly one is active at a time and
clicking the active one again switches it off.
[b]Rotate UVs:[/b] toggling it shows an [b]Angle[/b] row in the right
panel - drag the slider or type a number from 0 to 360 degrees and the
islands turn live. The angle is ABSOLUTE for the current selection:
[b]0 is the position the face had when the rotation started[/b] and 360
is one full turn - the slider always shows the face's real total angle
and stays where you leave it (it does not snap back to 0). Rotations
with the quick 90-degree actions feed the same value. Changing the
selection or the tool starts a fresh chain at 0. The whole drag is ONE
undo step (a typed run is one step too).
[b]Scale UVs:[/b] toggling it shows a [b]Scale %[/b] row (10-400%), and
on the canvas you can grab any corner of the selection and drag: away
from the center grows, toward it shrinks - always UNIFORM, so the
aspect ratio never changes. Both tools re-derive every corner from the
frozen press-time positions, so long drags cannot drift.
Quick actions stay: the canvas right-click menu offers [b]Rotate UV
90° CW / CCW[/b], and on the canvas [b]R[/b] rotates clockwise,
[b]Shift+R[/b] counter-clockwise. One face turns about its own center;
several selected faces transform together as one rigid group, so the
faces of an island stay glued to each other. With [b]Snap[/b] on the
transformed corners land exactly on the texel grid - pixel-perfect,
like drags. Rotating and scaling move the SAMPLING window over the
atlas: the painted texels stay where they are and the face reads them
from the new mapping.
[color=#4da3ff]Use case:[/color] select a character face's island, press
R until the eyes sit level, fine-tune with the Angle slider, then paint
details with the island nicely aligned to the texel grid; use Scale to
fit a logo island onto a slightly smaller panel without stretching it.
[h2]Undo, Save & Open[/h2]
Everything meaningful is undoable (48 steps): modeling, UV edits,
painting, resolution changes, renames, visibility/lock, deletes.
Ctrl+Z undoes, Ctrl+Shift+Z (or Ctrl+Y) redoes. [b]Save[/b] writes a
.pdoodle project (all objects, textures, UVs, paint colors and editor
settings). [b]Open[/b] restores one. The files are plain text - they
diff nicely in version control.
[b]Session auto-save[/b] - Polydoodle also keeps your work safe on its
own: a moment after every change the whole document (models, paint,
textures, settings) is stored in the editor's user data, and when you
close Godot it is flushed immediately. Reopen the editor and everything
is exactly where you left it - no save dialog, nothing to do. Opening a
.pdoodle project or deleting everything simply becomes the new session.
[h2]Import 3D Models[/h2]
The [color=#4da3ff]Import Model[/color] button (arrow into a tray, next to
Open) brings an existing model into the scene and keeps its textures.
[b]Supported files[/b] - Wavefront OBJ (with its .mtl and texture maps),
glTF / GLB, FBX, and Godot scenes or meshes that live inside the project
(.tscn, .scn, .tres, .res, .mesh).
[b]What happens to the model[/b] - duplicate vertices are welded, flat
triangle pairs are merged into quads, and the model is scaled to fit a
2-unit box and centered. Every mesh in the file becomes its own object, so
you can edit, hide or export the parts separately. The whole import is a
single undo step.
[b]Textures[/b] - Polydoodle paints every face into its own island of one
atlas, so the model's texture is [i]re-baked[/i] into those islands rather
than copied. Materials without a texture import as flat colors, tiling UVs
repeat as in the original, and several materials in one mesh are kept. The
atlas resolution follows the source texture (256 / 512 / 1024); you can
change it afterwards in the Texture Resolution setting.
[b]Where from[/b] - the file picker browses your whole computer, not only
the project, and offers an "All files" filter. Duplicate faces that some
exporters write twice are removed so nothing z-fights.
[b]Limits[/b] - up to 5000 faces after cleanup and 32 meshes per file.
Above 1500 faces a note warns that painting and editing get slower; this
is a low-poly tool, so lighter models always feel best.
Large imports show their progress in the status bar and never freeze the
editor. Anything that could not be imported (a missing texture file, a
broken face) is listed in a notes dialog after the import.
[b]Tips[/b] - for OBJ keep the .mtl and texture files next to the .obj (or at
the paths the .mtl names). Skinned or animated models import in their rest
pose; animation, rigs and normal / roughness maps are not imported.
[h2]Export for Godot[/h2]
[color=#4da3ff]Mesh (.tres)[/color] - an ArrayMesh with the painted texture
and correct UVs; assign it to any MeshInstance3D.
[color=#4da3ff]Scene (.tscn)[/color] - a small scene wrapping the mesh.
[color=#4da3ff]OBJ[/color] - a Wavefront OBJ with flat shading ("s off"), a
companion .mtl and the atlas saved as PNG per textured object. Imports
into Blender/Unity/Godot with the texture.
[color=#4da3ff]Add to current scene[/color] - drops a PolydoodleModel
MeshInstance3D into the edited scene, selected and ready. Exporting again
LATER UPDATES that same node in place: the mesh, UVs and texture are
swapped, while the position, rotation and scale you set in the Godot
editor (and any children) stay untouched. With several Polydoodle models
in one scene, select the one to update before exporting.
[h2]Keyboard & Mouse Map[/h2]
[font_size=12][table=3]
[cell]1 / 2 / 3 / 4[/cell][cell]Object / Vertex / Edge / Face mode[/cell][cell][/cell]
[cell]5[/cell][cell]Draw mode[/cell][cell][/cell]
[cell]6[/cell][cell]Toggle workspace (3D <-> Texture)[/cell][cell][/cell]
[cell]G / S / R (3D)[/cell][cell]Move / Scale / Rotate gizmo (active key again = hide)[/cell][cell][/cell]
[cell]T / V / B[/cell][cell]Snap / Grid visibility / Both sides[/cell][cell][/cell]
[cell]Ctrl+Z, Ctrl+Shift+Z[/cell][cell]Undo / Redo[/cell][cell][/cell]
[cell]Ctrl+D[/cell][cell]Duplicate selection[/cell][cell][/cell]
[cell]Ctrl+A[/cell][cell]Select all[/cell][cell][/cell]
[cell]Del / Backspace[/cell][cell]Delete selection[/cell][cell][/cell]
[cell]F[/cell][cell]Frame selection[/cell][cell][/cell]
[cell]Space[/cell][cell]Fullscreen the focused viewport[/cell][cell][/cell]
[cell]Esc[/cell][cell]Deselect / cancel sticker[/cell][cell][/cell]
[cell]Shift+Click[/cell][cell]Add to selection[/cell][cell][/cell]
[cell]Ctrl+LMB drag (3D)[/cell][cell]Rectangle multi-select[/cell][cell][/cell]
[cell]LMB / RMB / MMB[/cell][cell]Tool action / pan / orbit[/cell][cell][/cell]
[cell]Alt+LMB[/cell][cell]Orbit while drawing or painting[/cell][cell][/cell]
[cell]Wheel[/cell][cell]Zoom (scale stickers while importing)[/cell][cell][/cell]
[cell]Right-click (sticker)[/cell][cell]Rotate the image 90 degrees[/cell][cell][/cell]
[cell]R / Shift+R (UV canvas)[/cell][cell]Rotate UV selection 90 CW / CCW[/cell][cell][/cell]
[cell]Rotate/Scale toolbar toggles[/cell][cell]Angle 0-360 / Scale 10-400% rows in the right panel; Scale also drag-to-scale any corner[/cell][cell][/cell]
[cell]Right-click (canvas, Edit UV)[/cell][cell]Mesh ops menu[/cell][cell][/cell]
[cell]Right-click (3D or 2D view, edit modes)[/cell][cell]Mesh ops menu[/cell][cell][/cell]
[cell]Ctrl/Shift+click (hierarchy)[/cell][cell]Multi-select objects[/cell][cell][/cell]
[/table][/font_size]
[h2]Use Cases & Workflows[/h2]
[color=#4da3ff]A low-poly house:[/color] add a Cube, scale it with the Scale
gizmo; add a Prism for the roof; select both and extrude nothing - just
paint: switch to the Texture Editor, fill the walls island with cream,
the roof island with red, draw windows with the Pixel brush in Pixel
mode. Export as OBJ for a game jam or .tres to use directly.
[color=#4da3ff]A character head:[/color] add a Sphere, merge the bottom
vertices flat, extrude the top face twice for a hat. In Edit UV, detach
the face island, place it on empty atlas space, rotate it upright with
Rotate UV if needed, and paint the face with the brush (Smooth mode) -
the islands stay exactly where you packed them.
[color=#4da3ff]Pixel-art sprite on a plane:[/color] add a Plane, set
resolution 64, filter PIXEL, and draw with the Pixel brush at size 1 -
the plane IS your sprite sheet. Export .tres and use it in-game.
[color=#4da3ff]Level grayboxing:[/color] draw rectangles on the ground in
Draw mode, extrude the faces to wall height with the Face context menu,
duplicate around, then add everything to the current scene.
[h2]Troubleshooting[/h2]
[b]The canvas says "Select an object..."[/b] - the texture editor edits
the ACTIVE object; add or select one first.
[b]Painting does nothing on an object[/b] - it is locked or hidden
(padlock/eye in the hierarchy). Unlock it.
[b]UVs look scrambled after heavy vertex drags[/b] - the mapping
re-derives from the new geometry on the next edit; use Reset UVs (Edit
UV menu) or the toolbar button for a clean planar unwrap.
[b]A fill landed on the "wrong" island[/b] - fills repaint the face's
island at its CURRENT position; the island may simply overlap another
one's area - detach it to free space.
[b]Imported image invisible[/b] - the atlas may be much larger than the
sticker at scale 1.0; wheel it up, or check that the active object is
the one you imported onto.
[b]A message appears at the top of the viewport[/b] - Polydoodle tells you
why an action cannot run right now and what to do: no shape in the scene,
nothing selected, the wrong mode (for example Extrude needs Face mode, key
4), a locked or hidden shape, nothing to undo, or a doodle that was too
small. The message fades by itself and never blocks the mouse.
[b]Clicking a shape does nothing[/b] - it is probably locked (padlock icon
in the hierarchy) or hidden (eye icon). A notice names the shape; unlock or
show it to edit it.
[b]The gizmo is not showing[/b] - nothing is selected, the selection is
hidden, or the shape has no geometry. Select a shape (Object mode) or
vertices / edges / faces, and the gizmo appears on the selection.
[b]Export does nothing[/b] - the scene is empty or every shape is hidden;
a notice says which.
[b]Import says the model has too many faces[/b] - the limit is 5000 faces.
Decimate or retopologize the model in your 3D software and import again.
[b]An imported model is white or checkered[/b] - its texture file was not
found (see the notes dialog after importing). For OBJ, keep the texture next
to the .obj / .mtl; for glTF use a .glb or keep the image files beside the
.gltf.
[b]Import is not available for a file type[/b] - scenes and meshes (.tscn,
.tres, ...) must be inside the project; OBJ, glTF / GLB and FBX can be
anywhere on your computer.
[b]Export OBJ looks smooth in another app[/b] - the OBJ is written with
"s off" (flat); some importers override shading - re-import or disable
smooth shading there.
"""
## Build (once) and show the documentation window. The caller parents the
## window into the editor's base control and centers it on screen
## (an unpositioned Window opens in the top-left corner).
static func open(existing: Window) -> Window:
if existing != null and is_instance_valid(existing):
existing.show()
existing.move_to_foreground()
return existing
var win := Window.new()
win.title = "Polydoodle Documentation"
win.min_size = Vector2i(760, 520)
win.size = Vector2i(920, 640)
var v := VBoxContainer.new()
v.set_anchors_and_offsets_preset(Control.PRESET_FULL_RECT)
v.offset_left = 8
v.offset_top = 8
v.offset_right = -8
v.offset_bottom = -8
win.add_child(v)
var head := HBoxContainer.new()
head.add_theme_constant_override("separation", 8)
v.add_child(head)
var icon := TextureRect.new()
icon.texture = PdIcons.get_icon("docs")
icon.custom_minimum_size = Vector2(24, 24)
icon.stretch_mode = TextureRect.STRETCH_KEEP_ASPECT_CENTERED
head.add_child(icon)
var title := Label.new()
title.text = "Polydoodle Documentation"
title.add_theme_font_size_override("font_size", 16)
head.add_child(title)
# top-line links (see the URL_* constants above): the plugin page, a
# rate link and the author's other works - replace the URLs anytime
var spacer := Control.new()
spacer.size_flags_horizontal = Control.SIZE_EXPAND_FILL
spacer.size_flags_vertical = Control.SIZE_SHRINK_CENTER
head.add_child(spacer)
for pair in [["Godot Plugin", URL_PLUGIN],
["Rate This Plugin", URL_RATE],
["My Other Works", URL_OTHER]]:
var lb := LinkButton.new()
lb.text = pair[0]
lb.uri = pair[1] # LinkButton opens the URI in the OS browser
lb.add_theme_font_size_override("font_size", 13)
lb.focus_mode = Control.FOCUS_NONE
head.add_child(lb)
var split := HSplitContainer.new()
split.size_flags_vertical = Control.SIZE_EXPAND_FILL
split.size_flags_horizontal = Control.SIZE_EXPAND_FILL
split.split_offset = 190
v.add_child(split)
var list := ItemList.new()
list.custom_minimum_size = Vector2(180, 0)
list.size_flags_vertical = Control.SIZE_EXPAND_FILL
list.add_theme_font_size_override("font_size", 12)
list.auto_height = false
split.add_child(list)
var scroll := ScrollContainer.new()
scroll.size_flags_horizontal = Control.SIZE_EXPAND_FILL
scroll.size_flags_vertical = Control.SIZE_EXPAND_FILL
split.add_child(scroll)
var rt := RichTextLabel.new()
rt.bbcode_enabled = true
# fit_content would expand the label and hand scrolling to the outer
# ScrollContainer - then scroll_to_line() (which drives the label's OWN
# scrollbar) does nothing and clicking a section never moves the page.
# The label must own the vertical scroll for section navigation to work.
rt.fit_content = false
rt.size_flags_horizontal = Control.SIZE_EXPAND_FILL
rt.size_flags_vertical = Control.SIZE_EXPAND_FILL
# [h2] is not a supported tag in Godot 4.7 - render section headers
# manually (same line structure, so the section->line map stays valid)
# runtime link injection: the Welcome page opens with the same links
# the window's top line carries, so first-time readers see them first
var body: String = BODY.replace("[[RATE]]", URL_RATE) \
.replace("[[PLUGIN]]", URL_PLUGIN).replace("[[OTHER]]", URL_OTHER)
rt.text = body.replace("[h2]",
"[b][color=#4da3ff][font_size=17]").replace("[/h2]",
"[/font_size][/color][/b]")
rt.add_theme_font_size_override("normal_font_size", 13)
rt.add_theme_font_size_override("bold_font_size", 13)
scroll.add_child(rt)
# section -> first line in the bbcode body
var lines := body.split("\n")
for s in SECTIONS:
list.add_item(s[0])
var marker: String = "[h2]" + str(s[0])
var ln := 0
for i in lines.size():
if lines[i].begins_with(marker):
ln = i
break
list.set_item_metadata(list.item_count - 1, ln)
list.item_selected.connect(func(idx: int):
rt.scroll_to_line(int(list.get_item_metadata(idx))))
rt.meta_clicked.connect(func(meta: Variant):
OS.shell_open(str(meta)))
list.select(0)
win.close_requested.connect(func(): win.hide())
return win