Art Direction Document (ADD)

Project style: Cyber-Fantasy Impressionist Pixel Art Genre: 2D Metroidvania / action-platformer Visual inspiration: Hyper Light Drifter meets Castlevania: Symphony of the Night. These are mood references only. Every asset is original, and generation prompts never name those games (see CLAUDE.md).

Written by the owner on 2026-10-18. Sections 1 to 10 are the owner's text. The last section says how this project applies it.

1. Core vision and atmosphere

The visual identity is melancholic yet vibrant. It shows a fallen civilization where ancient stone architecture intertwines with forgotten, glowing high-tech machinery. The mood is mysterious, isolating and visually striking. It relies on heavy atmosphere rather than intricate realism.

2. Pixel art specifications and scale

• Resolution: chunky and minimalist. The game uses a low native resolution scaled up, so pixels are large and distinct.
• Detailing: impressionistic. Avoid over-detailing. Shapes and silhouettes must read at a glance. Use clusters of pixels to suggest texture (crumbling stone, rust) instead of drawing every crack or brick.
• Line art: no strict black outlines (sel-out). Use outlines only to separate elements of similar value, and colour them to match the lighting.

3. Colour palette

The palette is highly restricted and heavily stylized, moving away from naturalistic colours.

• Dominant tones (shadows and midtones): deep space blues, indigos, dark purples and pitch blacks. They create the heavy, oppressive void of the ruins.
• Highlights and accents (light sources): neon cyan, bright magenta and vivid violet. These are used strictly for emissive materials, technology and magical elements.
• Contrast rules: high contrast is mandatory. The neon accents must pop aggressively against the dark, moody backgrounds. Avoid muddy gradients.

4. Environment and level design

• Architecture: a seamless blend of gothic or ancient masonry (arches, pillars, statues) and brutalist sci-fi elements (cables, giant servers, neon screens, metal gratings).
• Nature: flora feels alien or mutated. Trees in the surface zones are barren and silhouetted against the sky. Underground areas may have bioluminescent fungi or glowing magenta vines.
• Parallax and depth:
• Foreground: pitch-black silhouettes framing the playable area.
• Midground (playable area): clearly readable platforms with defined edges. Contrast is highest here.
• Background: monochromatic or dual-tone layers that fade into dark indigo or deep purple. Detail drops sharply the further back a layer sits.

5. Lighting and shading

• Light sources: mostly diegetic and artificial (glowing screens, neon tubes, energy cores).
• Shading technique: minimal dithering. Prefer solid blocks of colour and sharp shadow terminators (cel-shading logic applied to pixel art).
• Silhouettes: characters and enemies have instantly recognizable silhouettes, often backlit by the glowing environment.

6. User interface (HUD)

• Aesthetic: wireframe, high-tech, minimalist.
• Colours: strictly monochromatic per element (for example pure cyan for the layout, pure magenta for the health bar), so each element stands out from the busy background.
• Typography: blocky sci-fi pixel fonts, no anti-aliasing.

7. Character design and animation

• Proportions and readability: characters are stylized with slightly exaggerated proportions so they read at a distance. Drop small details (individual belts, facial features) in favour of bold shapes: capes, large weapons, glowing visors.
• Animation style, snappy and impactful:
• Animations favour feel over fluid realism.
• Attacks use few frames so they feel instant and powerful, set against longer anticipation and recovery frames.
• Smear frames: heavy use of stylized smears for dashes and weapon swings, in pure neon colours to show speed.
• Idle and movement: idles stay subtle (breathing, cape waving) to contrast with the explosive movement in combat.

8. Enemy and boss design

• Thematic pillars: enemies reflect the world's lore: corrupted security drones, wildlife mutated by glowing energy, and ancient stone guardians infused with neon machinery.
• Visual hierarchy:
• Fodder and grunts: simple silhouettes, mostly dark, with one or two glowing weak points.
• Elites: more complex armour that emits more light, to draw the player's focus.
• Bosses: massive screen presence, combining organic fluidity with rigid, mechanical aggression.
• Telegraphing attacks: every enemy clearly telegraphs its attack, through a distinct colour flash (for example a weapon glowing bright magenta for 0.5 s before it strikes) or a dramatic, readable pose.

9. Visual effects and combat feedback

• VFX style: 100% 2D pixel art. No smooth alpha-blended particles: use hard-edged, chunky pixel clusters.
• Weapon trails and magic: sword slashes, projectiles and dashes leave glowing neon trails (cyan, magenta, or bright yellow for specific impacts). Trails linger for a few frames, then break up into geometric pixel dust.
• Impact and game feel:
• Hit stop: micro-pauses on significant impacts to convey weight.
• Sparks: clashes throw large, high-contrast, pure white or cyan sparks.
• Screen shake and chromatic aberration: subtle screen shake and RGB splitting on heavy explosions or boss roars, like a system glitch.

10. Asset generation and pipeline

• Tileset grid: every environment is built on a strict grid (for example 16x16 or 32x32 pixels, scaled up) so levels stay modular.
• Prop integration:
• Interactive props (chests, levers, breakables) use bright accent colours so they stand out at once from the background.
• Non-interactive background props (broken pillars, dead screens) blend into the midground and background palettes (dark blues and purples).
• Export rules: every asset is a crisp PNG with no anti-aliasing. One internal palette file is strictly enforced. No picking colours "by eye".

How Castle Crawler applies it

These are the prototype choices, first tried on the Lantern Row prologue.

• Palette: art/palette/cyber_fantasy.gpl (Aseprite / GIMP) and art/palette/cyber_fantasy.png are the one palette. The tools snap every pixel to it. The background layers use only its dark ramp plus the accents; the game layer alone uses the cooler, lighter slate ramp, so what you can stand on never shares a colour with what is behind it.
• Scale: the world grid is 32 game pixels per tile. Everything in the environment is drawn at 16 art pixels per tile and shown at x2: the game tileset, the room paintings (SDXL paints at 32 px per tile, box-filtered down to 16) and the city and foreground strips. Characters keep their 1:1 sprites for now.
• Layers, back to front: 1. City: paint_dir/sky.png, the slowest Parallax2D. Outdoor rooms (stage JSON "outdoor": true) have no ceiling: level.gd keeps the ceiling and the rock above it as invisible collision, so the city shows there. 2. Rooms: one AI-painted room per stage room (ComfyUI, paint_rooms.py), pushed dark and dual-tone by pixelate_rooms.py --background. An outdoor room's painting is cut to transparent above a jagged skyline of building tops (sky_rows in the stage JSON), so its facades stand against the city. 3. Game layer: the collision tiles, drawn as a crisp generated tileset (art/tools/make_pixel_tileset.py) in the slate ramp, plus the player, enemies and props. Every wall top has a light rim and one-way planks are neon-edged gratings over a hard shadow line, so platforms always read. 4. Foreground: black silhouettes (art/tools/make_foreground.py: rubble, railings, cables, the odd arch pillar) in a faster parallax layer.
• UI (section 6): game/assets/ui/add_theme.tres is the project theme (gui/theme/custom): the pixel font (Press Start 2P, OFL, in game/assets/ui/fonts/, imported with no anti-aliasing and no hinting) at its native 8 px, cyan text, and night buttons and inputs with a 1 px cyan border. Sizes stay multiples of 8 (16 for headings and notices, 24 for signs, 32 for the clock and titles). scripts/wire_box.gd draws the wireframe frames and bars: a 1 px outline with cut corners over a night backing. The screens drawn in code (gear and forge menu, results, chapter picker) take their font, colours and size snapping from scripts/ui_style.gd. Cyan is the layout, magenta the health bars (player and boss), losses and threats, violet the MP bar and masteries, yellow gold and the current pick; the map keeps cyan for open doors and the exit, magenta for shut doors and the boss, violet for locked doors and chests. Only ASCII in UI strings: the font has no other glyphs.
• Props (section 10): art/tools/palette_scenes.py rewrites the placeholder colour rects of every prop and creature scene onto the palette. Interactive props get bright accents by node name (chest violet with a yellow lock, lever with a magenta knob, keys yellow, shut doors magenta, switches and plates cyan or violet, the exit crystal cyan); their scripts switch between the light and dark shade of the same accent when used.
• Enemies (section 8): the same tool pushes every creature's body into the dark ramp by its original brightness and turns any bright, saturated part (eyes, lamps, cores) into a magenta weak point; bosses keep a violet second light on their bright armour. enemy.gd telegraphs every attack: while a creature's net_action is a windup state (every *WINDUP*, WIND, READY or AGITATED value of its Action enum) its body glows magenta on every peer.
• VFX (section 9): scripts/vfx.gd draws hard-edged pixel clusters (a scaled 1 px square, no alpha ramp): cyan sparks on every hit, magenta dust when a creature dies, and Vfx.impact() for boss roars and slams, which shakes every camera and splits the screen's colours through scripts/screen_fx.gd (an RGB-split shader the HUD adds to Main). The blade tip leaves a cyan Line2D smear during a swing that breaks into dust when it ends; thrown subweapons and enemy shots trail their own colour. Hit stop was already there. Subweapons are cyan (knife, axe), white (disc), magenta (flask) and violet (orbs); enemy shots are magenta, the Engine's gears violet, the Colossus's rocks purple.
• Not covered yet: the characters' real art (section 7: proportions, smear frames, idle animations) and the enemies' designs as creatures (section 8: drones, mutated wildlife, stone guardians) still wait on new Blender models; today they are palette placeholders. The player's sprite keeps its current render.