Excalibur icon indicating copy to clipboard operation
Excalibur copied to clipboard

Docs: improve documentation for graphics

Open KokoDoko opened this issue 1 year ago • 2 comments

Context

I find the documentation for working with graphics a bit confusing / contradictory (not talking about spritesheet animations).

  • There are pages for Graphics, GraphicsComponent, GraphicsGroup and GraphicsContext, and they cross reference each other.
  • There are mentions of canvas and raster graphics without explaining what that means.
  • The graphics component page has an example for graphicsgroup and even a paperdoll example with actors, but this is not mentioned on the actual graphicsgroup page
  • It's not really clear when to use a graphicsgroup and when to use the "paperdoll" child actors example
  • If someone just wants to draw a shape it's hard to find a simple code snippet.
  • The 0.29 release notes state that "Remove confusing Graphics Layering from ex.GraphicsComponent, recommend we use the ex.GraphicsGroup to manage this behavior", but this is not yet mentioned in the real docs.

Proposal

  • Merge the graphics page and the graphics component page
  • Move the paperdoll and graphicsgroup example from graphics component page to graphics group page
  • Explain when to use a graphicsgroup and when to use the "paper doll" style of child actors
  • Clarify if show hide is still needed or can we just do use() to replace a graphic
  • Explain the use case for using new Canvas()
  • The graphics page could start with simple examples for drawing shapes such as
const actor = new ex.Actor()
const circle = new ex.Circle({
  radius: 10,
  color: ex.Color.Red,
  strokeColor: Color.Red,
  lineWidth: .5
});
actor.graphics.use(circle);

KokoDoko avatar May 18 '24 09:05 KokoDoko

@KokoDoko 100% agree, this would be a net win

eonarheim avatar Jun 01 '24 13:06 eonarheim

This issue hasn't had any recent activity lately and is being marked as stale automatically.

github-actions[bot] avatar Aug 03 '24 00:08 github-actions[bot]