🔮 ⚡ Mystic Shield v3:
The Professional Teaching Edition

v2 has no file header. v3 opens with a block comment that names the sketch, its version, the author, the date, the canvas size, the color mode, and what a reader needs to understand to work with the file. This is the first thing a new programmer reads, and it should answer the question “what is this file for?” in four lines or fewer. The header should also name the one central p5.js concept the sketch demonstrates: layered drawing with independent rotation.

v2 has three constants at the top. v3 should have five named sections of constants, each preceded by a one-line comment that says what the section controls:

• Canvas — CANVAS_W, CANVAS_H. Naming these means changing canvas size never requires a text search.
• Animation — MANDALA_SPEED, STAR_SPEED (negative = counter-clockwise). The sign of the star speed is currently a silent magic number; naming it communicates intent.
• Geometry — all ring radii, satellite count, satellite orbit radius, satellite sizes, star size. Currently every number is raw; naming them means a student can find “what controls the satellite size” in one place.
• Color palette — one constant per visual element with a plain-English comment describing what it looks like (RING_OUTER_HUE = 33 — “burnt orange”). The palette comment block becomes a direct teaching moment about HSB.
• Spark behavior — SPARK_COUNT, speed range, size range, fade range. Currently these are anonymous literals scattered through the class.

HSB is invisible to beginners unless it is named. In v3, the colorMode(HSB, 360, 100, 100, 100) call should be preceded by a four-line comment block that explains the four parameters in plain English: Hue (0–360 degrees around the color wheel), Saturation (0 = grey, 100 = full color), Brightness (0 = black, 100 = full light), Alpha (0 = invisible, 100 = opaque). That comment turns one API call into one of the most important learning moments in the file.

Every function in v3 gets a one-to-three line block comment before it that answers three questions: what does this function draw or do, what coordinate system is active when it runs (canvas origin vs. translated center vs. a pushed rotation context), and what named constants it depends on. This comment is not for experts — it is for a student trying to locate where “the ring in the middle” is drawn. The draw() function gets the most important comment in the file: a numbered list of the drawing layers in order, explaining that later layers draw on top of earlier ones, and why the sparks must come before the rings.

The single most important concept in any animated sketch is the drawing order. In v2, draw() has no comments at all. In v3, the function opens with a block that reads like a painter’s instruction list:

1. Background — clears the previous frame; everything after this is fresh
2. Sparks — drawn first so the rings appear in front of them
3. Mandala rings — the slowly rotating concentric structure
4. Star array — drawn last, counter-rotating, appears on top of rings

Each of the four push/pop blocks in draw() gets an inline comment naming the layer. A student reading v3 will understand z-order before they understand push().

The Spark class in v2 is correct but opaque. In v3:

• The class header explains the lifecycle in one sentence: a spark is born near the center, travels outward, fades as it goes, and resets when it reaches the edge.
• The constructor comment lists each property and what it controls.
• reset() gets a comment noting it is called both on construction (via the constructor) and on expiry (via update()) — this is the non-obvious part that trips up beginners.
• update() names the lifecycle check explicitly: if radius exceeds canvas boundary, restart this spark.
• display() explains the map() call in plain English: the farther from center, the lower the alpha — map() converts the radius into a 0–1 life ratio, then multiplies by 100 to get the HSB alpha value. This is the trickiest math in the sketch and deserves the most comment.

The satellite sigil loop and the Spark display() method both use polar → Cartesian conversion (x = r × cos(θ), y = r × sin(θ)). In v2 this appears without explanation. In v3, the first time this pattern appears it gets a comment: polar coordinates — convert (radius, angle) to (x, y) on the Cartesian plane. The satellite loop reinforces this by naming the variable orbitAngle rather than just i * (TWO_PI / count), making the geometry readable.

v2 embeds the full sketch source as a String.raw template literal in the HTML <head>. For v3, the sketch is ~230 lines with all its teaching comments — duplicating that in the HTML creates a maintenance hazard: any change to the sketch would require updating both the JS file and the HTML string. The fetch() approach loads the already-running sketch file as text for the greenbar display, keeping exactly one copy of the source.

v3 produces the same visual as v2. It shares mysticShield2Styles.css (all fire/amber color tokens, greenbar theme, canvas panel, page nav) and scripts/mysticShield2Scripts.js (buildCodeDisplay(), copyRaw(), applyKW/applyNM). Creating separate v3 style and script files would duplicate 300+ lines for no visual gain. When a future version needs distinct styling, a v3-specific stylesheet can be added at that point.

The Session 1 plan named the spark birth constants SPARK_BIRTH_MIN and SPARK_BIRTH_MAX. During implementation these were renamed to SPARK_BIRTH_NEAR and SPARK_BIRTH_FAR. The MIN/ MAX naming is correct for a speed or size range, but birth radius communicates spatial distance — “near” and “far” are more descriptive for that concept and align with the way the Spark comments explain the lifecycle (“born near the center”). The map() call in display() uses SPARK_BIRTH_NEAR as its lower bound, making the intent immediately clear.

Including P2D is a style/pedagogy decision, not a correctness one. The rule of thumb: in a learning-focused file, make the default explicit when knowing the default exists is itself a teaching moment. In production code, omit it — the shorter signature is idiomatic p5.js for 2D sketches.

The v2 App Comparison has six concept cards. v3 earns a seventh: how each language declares an immutable named value. This is one of the most transferable ideas in software engineering and the core of what v3 adds to v2.

In the Java Spark class, the dot diameter field is named sz rather than size. Processing’s global size() function is a method name in the Java environment; declaring a field named size does not cause a compile error but can confuse students who expect size(800, 600) to still refer to the canvas setup call. Using sz eliminates the ambiguity. The v3 Spark class header comment documents this decision explicitly. The JavaScript and Python versions retain this.size and self.size because neither environment has this naming conflict.

The full MysticShield3Sketch.js file includes detailed multi-line function header blocks and an HSB explainer comment block (about 230 lines total). In the v3 App Comparison panels, the code strings use the section-divider structure and key per-line comments but compress the verbose header blocks to single-line summaries. This keeps the three panels comparable in height while preserving the essential named-constant and painter’s-algorithm documentation. The full source files (.pde and .py) and the v3 showcase page (mysticShield3.html) carry the complete documentation.

Processing executes the sketch lifecycle in this order: settings() → setup() → draw(). Only settings() may call size(), fullScreen(), or smooth() with non-literal arguments. This is a Processing 3+ design: the renderer must be initialized before setup() runs.

The v2 Java file was unaffected because it used literal integers (800, 600) in setup(). v3 introduced CANVAS_W and CANVAS_H — which is exactly the right professional practice — but exposed this Processing constraint for the first time. The fix is a two-line change: add settings(), remove size() from setup().

The Entry #1 card in creativeCrossTrainingHome.html was updated:

• Card click now navigates to mysticShield3.html (v3 showcase)
• Card description updated: “v3 replaces every magic number with a named constant … v2 is available for before–and–after comparison”
• Concept label updated to Entry #1 — v3 Edition
• Footer links reordered: v3 showcase • v3 app comparison • v2 (compare) • interactive • movie clip

The rationale: the CCT home is a first impression, not a teaching sequence. The v2 → v3 progression story is embedded in the Mystic Shield pages themselves (chatlog, intro card on v3.html, App Comparison note card). Featuring v3 on the gallery home shows best work without losing the evolution narrative.

The note card already mentioned that Java requires settings() for named-constant sizing. Adding the DWR cross-reference turns that sentence into a gateway to the full explanation: why the preprocessor imposes this restriction, what “duplicate settings()” actually means, and how v3’s professional standard — replacing magic numbers with named constants — is what causes the constraint to surface. The DWR entry is the right place for that depth; the App Comparison note card is the right place for the link.

The anchor id="dwr-34" was added to the DWR table row so the link (../../dwrEureka.html#dwr-34) lands directly on the entry rather than dropping the reader at the top of a long page.