Vibeship-spawner-skills level-design

id: level-design

install

source · Clone the upstream repo

git clone https://github.com/vibeforge1111/vibeship-spawner-skills

manifest: game-dev/level-design/skill.yaml

Safe Zone Design

The Safety Bubble Pattern

Before any challenge, provide:

Clear overview of the space
Observation point (see before doing)
Safe practice area (fail without consequence)
Gradual difficulty ramp

Nintendo's Teaching Method

SAFE: Introduce mechanic in zero-risk setting
GUIDED: Simple challenge with clear solution
TWIST: Add complexity or combine mechanics
MASTERY: Test full understanding

Example: Teaching Wall Jump

Room 1: Pit with spikes, but respawn is instant
        and landing pad is obvious. Learn timing.

Room 2: Same mechanic, now over longer pit.
        Builds confidence.

Room 3: Wall jump PLUS moving platform.
        Combines with existing skill.

Room 4: Full challenge with meaningful stakes.
        Player has earned this difficulty.

Key Principle

Players should understand a mechanic BEFORE they're punished for failing it.

name: Lock and Key Gating description: Control progression through various gating mechanisms when: Designing metroidvania, RPG, or any game with progression-based exploration example: |

Gating Types

Hard Gates (Absolute Blocks)
- KEY GATES: Literal keys, keycards, passwords
- ABILITY GATES: Requires specific power (double jump, grapple)
- STORY GATES: Plot event must trigger first
- NPC GATES: Character blocks until condition met
Soft Gates (Skill/Resource Dependent)
- COMBAT GATES: Enemy too strong without leveling
- RESOURCE GATES: Need X items to proceed
- PUZZLE GATES: Solution requires observation/knowledge
- SKILL GATES: Technically possible, very difficult
Design Guidelines
1. Show the gate before players reach it "I can see where I need to go, just not how"
2. Make the unlock feel earned Key should require effort to obtain
3. Returning should feel rewarding New shortcuts, narrative callbacks, enemy placement changes
4. Avoid "find the key" hunts Key location should be hinted or logical
Metroidvania Pattern
```
[ Area A ] --> [GATE: Double Jump] --> [ Area B ]
     |                                      |
     v                                      v
[ Area C ] --> [GATE: Grapple] --> [ Area D ]

- Double Jump found in Area C
- Grapple found in Area B (after unlocking)
- Creates satisfying loop of unlock -> explore
```

name: Combat Arena Design description: Design spaces optimized for action gameplay with proper flow and pacing when: Creating areas where combat is the primary activity example: |

Combat Arena Principles

Shape Language

CIRCULAR: 360-degree threats, no safe corners
RECTANGULAR: Classic, provides corner refuges
ELONGATED: Ranged combat emphasis, flanking lanes
IRREGULAR: Organic feel, unpredictable cover
TIERED: Verticality creates positioning strategy

Cover and Flow

[ ] = Full Cover  [/] = Half Cover  [o] = Pillar

Bad Arena:                Good Arena:
+-------------+          +-------------+
|             |          |  [/]    [o] |
|             |          |      []     |
|             |          |  [o]    [/] |
+-------------+          +-------------+

Cover placement creates:
- Movement decisions
- Tactical positioning
- Breather opportunities
- Interesting combat dance

Entry/Exit Points

Entry: Give player overview before entering
During: Lock doors or spawn waves
Exit: Clearly different from entry
Reward: Loot, narrative beat, vista

Wave Design

First wave: Tutorial wave, low threat
Middle waves: Escalating difficulty
Final wave: Climax, new enemy or combo
Post-combat: Cooldown, resource pickup

Multiplayer Considerations

Spawn points have 3+ exit options
No spawn point has line-of-sight to another
Power positions are contestable, not impenetrable
Multiple routes to any objective

name: Metric Standards description: Define and adhere to consistent spatial measurements based on character controller when: Starting any level design project or blocking out spaces example: |

Level Design Metrics

Core Player Metrics (Establish First!)

CHARACTER_HEIGHT    = 1.8m (typical humanoid)
CROUCH_HEIGHT      = 0.9m
WALK_SPEED         = 3.5 m/s
RUN_SPEED          = 6.0 m/s
JUMP_HEIGHT        = 1.2m (comfortable)
JUMP_DISTANCE      = 3.0m (comfortable horizontal)
MAX_JUMP_DISTANCE  = 4.5m (skilled players only)

Space Standards

CORRIDOR_MIN_WIDTH     = CHARACTER_WIDTH * 2.5
CORRIDOR_COMBAT_WIDTH  = CHARACTER_WIDTH * 4
DOOR_HEIGHT            = CHARACTER_HEIGHT * 1.3
DOOR_WIDTH             = CHARACTER_WIDTH * 2
CEILING_COMFORTABLE    = CHARACTER_HEIGHT * 1.5
CEILING_OPPRESSIVE     = CHARACTER_HEIGHT * 1.1

Jump Distance Guidelines

TRIVIAL GAP       = JUMP_DISTANCE * 0.6  (no thought)
COMFORTABLE GAP   = JUMP_DISTANCE * 0.8  (standard)
CHALLENGING GAP   = JUMP_DISTANCE * 0.95 (focus required)
SKILL GAP         = JUMP_DISTANCE * 1.0  (tight timing)
IMPOSSIBLE GAP    = JUMP_DISTANCE * 1.2  (blocks path)

Sightline Standards

SNIPER_RANGE      = Effective weapon range * 1.2
ENGAGEMENT_RANGE  = 15-30m typical shooters
MELEE_ARENA       = 10-20m diameter
COMFORTABLE_VIEW  = 50-100m to landmarks

The Golden Rule

ALWAYS derive metrics from your character controller. Change the controller? Update all metrics immediately.

name: Teaching Without Tutorials description: Design levels that teach mechanics through play rather than text prompts when: Introducing any new mechanic, enemy, or system example: |

Wordless Teaching Design

The Valve Method (Portal, Half-Life 2)

ISOLATED INTRODUCTION Show mechanic alone, nothing else happening Player can't proceed without engaging
SAFE FAILURE First attempt has minimal punishment Instant respawn, no progress loss
OBSERVABLE SOLUTION Answer is visible if player looks NPCs or environment demonstrates
COMPLEXITY LAYERING Add one thing at a time Build on what player knows

Practical Example: Teaching Pressure Plates

Room 1: Door won't open. Pressure plate glows.
        No enemies. Player experiments.
        Standing on plate opens door.
        LESSON: Pressure plates open doors.

Room 2: Same setup, but box nearby.
        Player standing on plate, door opens.
        But they can't walk through while on plate.
        They see the box. Put box on plate.
        LESSON: Objects work too.

Room 3: Two plates required. One box.
        Player AND box needed.
        LESSON: Combination is possible.

Room 4: Real puzzle with stakes.
        Combines everything learned.
        MASTERY TEST.

The Questions Test

Before adding tutorial text, ask:

Can the environment teach this?
Can failure teach this safely?
Is there an observable solution?
Does player have time to experiment?

If all yes, no text needed.

name: Verticality and Sightlines description: Use height variation to create interesting spaces and strategic depth when: Designing any space larger than a single room example: |

Verticality Design

Why Verticality Matters

Creates tactical options (high ground advantage)
Provides natural landmarks and orientation
Enables layered exploration
Adds visual interest and scale
Creates dramatic reveals

Height Categories

DEPRESSION    : -2m to -5m (pits, trenches, basements)
GROUND LEVEL  : 0m (reference point)
LOW ELEVATION : +1m to +3m (platforms, small stairs)
MID ELEVATION : +4m to +8m (balconies, rooftops)
HIGH GROUND   : +10m+ (towers, cliffs, overviews)

Sightline Management

REVEAL SIGHTLINES
- Control what player sees first
- Frame destinations through openings
- Use elevation to show scale

BLOCKING SIGHTLINES
- Prevent seeing end from beginning
- Create mystery around corners
- Hide secrets behind geometry

COMBAT SIGHTLINES
- Long sightlines favor ranged combat
- Short sightlines favor melee/shotgun
- Broken sightlines create tension

The Vista Moment

After climbing or effort, reward with a view:

Shows progress (where player came from)
Shows goal (where player is going)
Provides moment of rest
Screenshot opportunity

Multiplayer Height Rules

High ground should be contestable
Multiple routes to elevated positions
Height advantage has counters (no fortress)
Spawn points at neutral elevation

anti_patterns:

name: Art Before Blockout description: Creating final art assets before proving the level is fun in graybox why: You'll spend weeks on art for spaces that get cut. Blockout changes are cheap, art changes are expensive. instead: Complete blockout, playtest, iterate until fun is proven. THEN begin art pass. Valve blocks out for months before any art.
name: The Maze description: Complex, winding paths with no orientation cues or landmarks why: Players get lost, frustrated, and quit. Looking at a map is not gameplay. instead: Use weenies, distinctive areas, and environmental cues. Players should always have a sense of direction.
name: Symmetric Multiplayer Maps description: Perfectly mirrored multiplayer maps with no distinctive landmarks why: Players can't call out positions effectively. "I'm at the pillar" - which one? Breaks team communication. instead: Asymmetric landmarks, color-coded areas, distinctive names. Mirror gameplay balance, not visuals.
name: Dead Ends Without Purpose description: Paths that lead nowhere and offer nothing why: Players feel punished for exploration. Breaks trust that the game rewards curiosity. instead: Every dead end has a reward - loot, lore, shortcut unlock, or at minimum a vista. Or eliminate the path entirely.
name: Backtracking Without Change description: Forcing players to walk through the same space again with nothing new why: Backtracking feels like padding. Players notice when you waste their time. instead: Change the space (new enemies, opened shortcuts, environmental shift) or create one-way flow.
name: The Difficulty Cliff description: Sudden spike in difficulty without proper teaching ramp why: Players feel the game is unfair. They didn't fail because they're bad, they failed because you didn't teach them. instead: Gradual difficulty curves. Test every new challenge - if most players fail first try, the teaching failed.
name: Metric Violations description: Jumps that require pixel-perfect timing, corridors too narrow for combat why: Players can't articulate why something feels bad, but they feel it. Inconsistent metrics destroy trust. instead: Establish metrics from character controller. Use them religiously. Comfortable margins everywhere.
name: Linear Open World description: Open world map where all content is encountered in fixed order anyway why: Open world promises player agency. Linear content in open wrapper is a lie. instead: If content is linear, make the space linear. If space is open, make content truly optional/reorderable.
name: Exhaustive Exploration Required description: Hiding critical items in obscure locations with no hints why: Most players won't explore every corner. Required items should be findable by typical players. instead: Critical path items on main route or clearly hinted. Obscure locations for optional bonuses only.
name: Tutorial Text Overload description: Stopping gameplay to show text explaining mechanics why: Breaks flow. Players skip text. Learning by doing is more memorable. instead: Design spaces that teach through play. Text only when absolutely unavoidable.

handoffs:

trigger: art direction|textures|materials|environment art|3d assets|foliage to: environment-art context: Level blockout complete, needs art pass priority: 1
trigger: lighting|mood|atmosphere|time of day|shadows to: lighting-design context: Geometry locked, needs lighting pass priority: 1
trigger: game mechanics|systems|balance|progression systems|ability design to: game-design context: Level design needs core mechanics defined first priority: 1
trigger: story|narrative|dialogue|lore|characters|plot to: narrative-design context: Level needs story integration or environmental narrative priority: 2
trigger: audio|sound design|music|ambience|sfx to: audio-design context: Level needs audio pass for atmosphere priority: 2
trigger: UI|HUD|minimap|waypoints|markers|compass to: ui-design context: Level needs navigation UI support priority: 3

Vibeship-spawner-skills level-design

Three-Beat Structure

Beat 1: Setup (20-30% of level)

Beat 2: Confrontation (50-60% of level)

Beat 3: Resolution (15-25% of level)

Push and Pull Rhythm

The Pattern

PUSH Spaces (20-40% of playtime)

PULL Spaces (40-60% of playtime)

Why It Works

Common Mistake

Weenie Design (Term from Walt Disney)

What is a Weenie?

Hierarchy of Landmarks

Implementation

Famous Examples

Breadcrumbing Techniques

Light as Primary Guide

Composition and Framing

Environmental Hints

The Valve Method (Left 4 Dead / Half-Life)

Test: The Blur Test