Lesson 9: Prism Quest - Entity Multiplication

Your dimensional world needs more inhabitants! In your complete Prism Quest from lessons 1-8, you navigated dimensional mazes alone. Today, you’ll populate your world with multiple dimensional navigators, spectral entities, and attribute-based beings that create a rich, interactive dimensional ecosystem. You’ll master arrays and data structures through memory-efficient multi-entity management that transforms your solitary quest into a bustling dimensional adventure!

Your Dimensional Entities Multiply

Let’s create a multi-entity dimensional world using arrays and efficient memory management:

; Prism Quest - Entity Multiplication System
    ORG $8000
    
start:
    ; Initialize complete Spectrum environment
    CALL clear_complete_screen
    
    ; Set up enhanced dimensional world for multiple entities
    CALL init_complete_dimensional_state
    
    ; Initialize new multi-entity systems
    CALL init_entity_multiplication_system
    CALL init_navigator_array_system
    CALL init_spectral_entity_system
    CALL init_dimensional_spawning_system
    
    ; Create entity-ready dimensional world
    CALL create_multi_entity_dimensional_world
    
    ; Entity Multiplication main loop
entity_multiplication_loop:
    ; Process all navigator input
    CALL read_complete_input
    
    ; Update primary navigator
    CALL update_primary_navigator
    
    ; Update entity multiplication systems
    CALL update_navigator_entities
    CALL update_spectral_entities
    CALL process_dimensional_spawning
    
    ; Process all multi-entity interactions
    CALL process_multi_entity_collisions
    CALL update_entity_attribute_effects
    
    ; Update visual and audio systems
    CALL update_multi_entity_effects
    CALL update_dimensional_audio
    CALL update_entity_status_display
    
    ; Check for dimensional victory conditions
    CALL check_multi_entity_victory
    
    JR entity_multiplication_loop

; Initialize entity multiplication system using efficient arrays
init_entity_multiplication_system:
    ; Set up entity management using structured data organization
    CALL init_navigator_entity_arrays
    CALL init_spectral_entity_arrays
    CALL init_attribute_entity_arrays
    CALL init_spawn_management_system
    
    ; Initialize entity counters for memory management
    LD A, $00           ; No active entities initially
    LD (active_navigator_count), A
    LD (active_spectral_count), A
    LD (active_attribute_count), A
    
    ; Set entity limits for Spectrum memory optimization
    LD A, $06           ; Maximum 6 navigators (memory efficient)
    LD (max_navigator_count), A
    LD A, $08           ; Maximum 8 spectral entities
    LD (max_spectral_count), A
    LD A, $04           ; Maximum 4 attribute entities
    LD (max_attribute_count), A
    
    RET

; Initialize navigator entity arrays using data structures
init_navigator_entity_arrays:
    ; Navigator position data structure (6 navigators max)
    LD HL, navigator_position_data
    LD (navigator_array_pointer), HL
    
    ; Clear navigator position arrays
    LD B, 6             ; Number of navigators
    LD HL, navigator_x_array
clear_navigator_positions:
    LD (HL), $00        ; Inactive navigator marker
    INC HL              ; Next position
    LD (HL), $00        ; Clear Y position
    INC HL              ; Next navigator
    DJNZ clear_navigator_positions
    
    ; Clear navigator state arrays
    LD B, 6             ; Number of navigators
    LD HL, navigator_active_array
clear_navigator_states:
    LD (HL), $00        ; Inactive
    INC HL              ; Next state
    LD (HL), $00        ; Clear type
    INC HL              ; Next navigator data
    DJNZ clear_navigator_states
    
    ; Initialize navigator movement data
    LD HL, navigator_velocity_data
    LD B, 12            ; 6 navigators × 2 velocities each
clear_navigator_velocities:
    LD (HL), $00        ; Clear velocity
    INC HL              ; Next velocity
    DJNZ clear_navigator_velocities
    
    RET

; Initialize spectral entity arrays for dimensional beings
init_spectral_entity_arrays:
    ; Spectral entity data structure (8 entities max)
    LD HL, spectral_entity_data
    LD (spectral_array_pointer), HL
    
    ; Clear spectral position arrays
    LD B, 8             ; Number of spectral entities
    LD HL, spectral_x_array
clear_spectral_positions:
    LD (HL), $00        ; Inactive marker
    INC HL
    LD (HL), $00        ; Clear Y
    INC HL
    DJNZ clear_spectral_positions
    
    ; Clear spectral state arrays
    LD B, 8             ; Number of spectral entities
    LD HL, spectral_active_array
clear_spectral_states:
    LD (HL), $00        ; Inactive
    INC HL
    LD (HL), $01        ; Default spectral type
    INC HL
    LD (HL), $00        ; Default dimensional phase
    INC HL
    DJNZ clear_spectral_states
    
    RET

; Create multi-entity dimensional world
create_multi_entity_dimensional_world:
    ; Create expanded dimensional maze for multiple entities
    CALL create_expanded_dimensional_maze
    
    ; Set up entity spawn zones throughout dimensions
    CALL setup_dimensional_spawn_zones
    
    ; Create attribute-based interaction zones
    CALL create_attribute_interaction_zones
    
    ; Initialize multi-entity visual elements
    CALL init_multi_entity_visual_system
    
    RET

; Create expanded dimensional maze for entity navigation
create_expanded_dimensional_maze:
    ; Draw larger maze structure for multiple entities
    LD HL, $4000        ; Screen memory start
    LD DE, expanded_maze_pattern
    LD BC, 768          ; Copy maze pattern (24 × 32 characters)
    LDIR                ; Copy maze to screen
    
    ; Set up enhanced attribute zones for entity differentiation
    LD HL, $5800        ; Attribute memory start
    LD B, 24            ; Number of lines
    
create_entity_attributes_loop:
    PUSH BC             ; Save line counter
    LD C, 32            ; Characters per line
    
create_line_attributes:
    LD A, B             ; Use line number for color variation
    AND $07             ; Mask to valid colors
    ADD A, $40          ; Bright colors for entity visibility
    LD (HL), A          ; Set attribute
    INC HL              ; Next character
    DEC C               ; Decrement character counter
    JR NZ, create_line_attributes
    
    POP BC              ; Restore line counter
    DJNZ create_entity_attributes_loop
    
    RET

; Update navigator entities using array processing
update_navigator_entities:
    ; Process all active navigators using efficient iteration
    LD B, 6             ; Maximum navigators
    LD HL, navigator_active_array
    LD IX, navigator_x_array
    
update_navigator_loop:
    ; Check if this navigator is active
    LD A, (HL)          ; Load active flag
    CP $00              ; Check if inactive
    JR Z, next_navigator ; Skip if inactive
    
    ; Update this navigator's movement
    CALL update_navigator_movement
    
    ; Update this navigator's dimensional interaction
    CALL update_navigator_dimensional_interaction
    
    ; Update this navigator's visual representation
    CALL update_navigator_display
    
next_navigator:
    INC HL              ; Next active flag
    INC HL              ; Skip type byte
    INC IX              ; Next navigator X position
    INC IX              ; Next navigator Y position
    DJNZ update_navigator_loop
    
    RET

; Update navigator movement using velocity data
update_navigator_movement:
    ; B contains navigator index, IX points to position data
    PUSH BC             ; Save navigator index
    
    ; Calculate velocity array offset
    LD A, B             ; Navigator index
    SUB 6               ; Convert to 0-based
    NEG                 ; Make positive
    ADD A, A            ; × 2 for X,Y velocities
    LD C, A             ; Velocity offset
    
    ; Update X position
    LD A, (IX+0)        ; Current X position
    LD HL, navigator_velocity_x_array
    ADD HL, BC          ; Point to velocity
    ADD A, (HL)         ; Add velocity
    LD (IX+0), A        ; Store new X
    
    ; Update Y position
    LD A, (IX+1)        ; Current Y position
    LD HL, navigator_velocity_y_array
    ADD HL, BC          ; Point to velocity
    ADD A, (HL)         ; Add velocity
    LD (IX+1), A        ; Store new Y
    
    ; Check dimensional boundaries
    CALL check_navigator_dimensional_boundaries
    
    POP BC              ; Restore navigator index
    RET

; Update spectral entities with dimensional behavior
update_spectral_entities:
    ; Process all active spectral entities
    LD B, 8             ; Maximum spectral entities
    LD HL, spectral_active_array
    LD IX, spectral_x_array
    
update_spectral_loop:
    ; Check if this spectral entity is active
    LD A, (HL)          ; Load active flag
    CP $00              ; Check if inactive
    JR Z, next_spectral ; Skip if inactive
    
    ; Update spectral entity behavior based on type
    INC HL              ; Point to type
    LD A, (HL)          ; Load spectral type
    CP $01              ; Wandering spectral
    JR Z, spectral_wandering_behavior
    CP $02              ; Chasing spectral
    JR Z, spectral_chasing_behavior
    CP $03              ; Dimensional guardian
    JR Z, spectral_guardian_behavior
    
    ; Default behavior
    JR spectral_default_behavior

spectral_wandering_behavior:
    ; Random-like movement through dimensions
    LD A, (IX+0)        ; Current X
    ADD A, $01          ; Simple movement
    AND $1F             ; Keep in bounds (0-31)
    LD (IX+0), A        ; Store new X
    
    LD A, (IX+1)        ; Current Y  
    ADD A, $01          ; Simple movement
    AND $17             ; Keep in bounds (0-23)
    LD (IX+1), A        ; Store new Y
    
    JR spectral_behavior_complete

spectral_chasing_behavior:
    ; Chase nearest navigator
    CALL find_nearest_navigator
    
    ; Move toward target (simplified AI)
    LD A, (target_navigator_x)
    CP (IX+0)           ; Compare with spectral X
    JR C, spectral_move_left
    
    ; Move right
    LD A, (IX+0)
    INC A
    LD (IX+0), A
    JR spectral_check_y
    
spectral_move_left:
    LD A, (IX+0)
    DEC A
    LD (IX+0), A
    
spectral_check_y:
    LD A, (target_navigator_y)
    CP (IX+1)           ; Compare with spectral Y
    JR C, spectral_move_up
    
    ; Move down
    LD A, (IX+1)
    INC A
    LD (IX+1), A
    JR spectral_behavior_complete
    
spectral_move_up:
    LD A, (IX+1)
    DEC A
    LD (IX+1), A
    JR spectral_behavior_complete

spectral_guardian_behavior:
    ; Guard specific dimensional zones
    ; Get guardian zone from type data
    DEC HL              ; Back to type
    INC HL              ; Forward to phase
    LD A, (HL)          ; Load dimensional phase
    
    ; Calculate guard position based on phase
    ADD A, A            ; × 2
    ADD A, A            ; × 4
    ADD A, $08          ; Base guard position
    LD (IX+0), A        ; Set guard X
    
    LD A, (HL)          ; Load phase again
    ADD A, A            ; × 2
    ADD A, $06          ; Base guard Y
    LD (IX+1), A        ; Set guard Y
    
    JR spectral_behavior_complete

spectral_default_behavior:
    ; Simple oscillation
    LD A, (IX+0)
    XOR $01             ; Toggle bit for simple oscillation
    LD (IX+0), A

spectral_behavior_complete:
    DEC HL              ; Back to active flag for next iteration

next_spectral:
    INC HL              ; Next active flag
    INC HL              ; Skip type
    INC HL              ; Skip phase
    INC IX              ; Next spectral X
    INC IX              ; Next spectral Y
    DJNZ update_spectral_loop
    
    RET

; Process dimensional spawning system
process_dimensional_spawning:
    ; Check if we should spawn new entities
    LD A, (active_navigator_count)
    LD B, A
    LD A, (max_navigator_count)
    CP B                ; Compare max with current
    JR C, no_navigator_spawn ; At maximum
    
    ; Check spawn timer
    LD A, (spawn_timer)
    DEC A
    LD (spawn_timer), A
    JR NZ, no_navigator_spawn
    
    ; Reset spawn timer (slower spawning for memory efficiency)
    LD A, $78           ; 120 frames = 2 seconds
    LD (spawn_timer), A
    
    ; Spawn new navigator
    CALL spawn_new_navigator
    
no_navigator_spawn:
    ; Check spectral entity spawning
    LD A, (active_spectral_count)
    LD B, A
    LD A, (max_spectral_count)
    CP B
    JR C, no_spectral_spawn
    
    ; Spawn new spectral entity
    CALL spawn_new_spectral_entity
    
no_spectral_spawn:
    RET

; Spawn new navigator in available slot
spawn_new_navigator:
    ; Find empty navigator slot
    LD B, 6             ; Maximum navigators
    LD HL, navigator_active_array
    
find_empty_navigator_slot:
    LD A, (HL)          ; Check active flag
    CP $00              ; Empty slot?
    JR Z, found_empty_navigator_slot
    INC HL              ; Next active flag
    INC HL              ; Skip type
    DJNZ find_empty_navigator_slot
    RET                 ; No empty slots
    
found_empty_navigator_slot:
    ; Activate this navigator slot
    LD A, $01
    LD (HL), A          ; Set active
    
    ; Set navigator type
    INC HL              ; Point to type
    CALL generate_navigator_type
    LD (HL), A          ; Store type
    
    ; Set spawn position
    CALL generate_navigator_spawn_position
    
    ; Increment active navigator count
    LD A, (active_navigator_count)
    INC A
    LD (active_navigator_count), A
    
    RET

; Generate navigator spawn position
generate_navigator_spawn_position:
    ; B contains slot index
    ; Calculate position array offset
    LD A, 6             ; Total slots
    SUB B               ; Get 0-based index
    ADD A, A            ; × 2 for X,Y
    LD C, A             ; Position offset
    
    ; Generate spawn X position (edge of screen)
    LD A, (dimensional_spawn_counter)
    AND $01             ; Alternate left/right
    JR Z, spawn_left_edge
    
    ; Spawn on right edge
    LD A, $1E           ; Right edge position
    JR store_spawn_x
    
spawn_left_edge:
    LD A, $02           ; Left edge position
    
store_spawn_x:
    LD HL, navigator_x_array
    ADD HL, BC          ; Point to position
    LD (HL), A          ; Store X
    
    ; Generate spawn Y position (random-ish)
    LD A, (dimensional_spawn_counter)
    AND $0F             ; Mask to 0-15
    ADD A, $04          ; Offset from edges
    INC HL              ; Point to Y position
    LD (HL), A          ; Store Y
    
    ; Update spawn counter
    LD A, (dimensional_spawn_counter)
    INC A
    LD (dimensional_spawn_counter), A
    
    RET

; Process multi-entity collisions
process_multi_entity_collisions:
    ; Check primary navigator vs other navigators
    CALL check_navigator_vs_navigator_collisions
    
    ; Check navigators vs spectral entities
    CALL check_navigator_vs_spectral_collisions
    
    ; Check spectral entities vs spectral entities
    CALL check_spectral_vs_spectral_interactions
    
    RET

; Check navigator vs navigator collisions
check_navigator_vs_navigator_collisions:
    ; Compare all active navigators with each other
    LD B, 6             ; Outer loop: first navigator
    LD HL, navigator_active_array
    LD IX, navigator_x_array
    
navigator_outer_loop:
    ; Check if outer navigator is active
    LD A, (HL)
    CP $00
    JR Z, next_outer_navigator
    
    ; Inner loop: check against other navigators
    PUSH BC             ; Save outer counter
    PUSH HL             ; Save outer active pointer
    PUSH IX             ; Save outer position pointer
    
    LD C, 6             ; Inner loop counter
    LD DE, navigator_active_array
    LD IY, navigator_x_array
    
navigator_inner_loop:
    ; Don't check navigator against itself
    LD A, B             ; Outer index
    CP C                ; Inner index
    JR Z, next_inner_navigator
    
    ; Check if inner navigator is active
    LD A, (DE)
    CP $00
    JR Z, next_inner_navigator
    
    ; Check collision between IX (outer) and IY (inner)
    CALL check_navigator_collision
    
next_inner_navigator:
    INC DE              ; Next inner active flag
    INC DE              ; Skip type
    INC IY              ; Next inner X
    INC IY              ; Next inner Y
    DEC C               ; Decrement inner counter
    JR NZ, navigator_inner_loop
    
    POP IX              ; Restore outer position
    POP HL              ; Restore outer active
    POP BC              ; Restore outer counter

next_outer_navigator:
    INC HL              ; Next outer active flag
    INC HL              ; Skip type
    INC IX              ; Next outer X
    INC IX              ; Next outer Y
    DJNZ navigator_outer_loop
    
    RET

; Update multi-entity visual effects
update_multi_entity_effects:
    ; Display all active navigators
    CALL display_navigator_entities
    
    ; Display all active spectral entities
    CALL display_spectral_entities
    
    ; Display entity interaction effects
    CALL display_entity_interaction_effects
    
    RET

; Display navigator entities with attribute effects
display_navigator_entities:
    LD B, 6             ; Maximum navigators
    LD HL, navigator_active_array
    LD IX, navigator_x_array
    
display_navigator_loop:
    ; Check if navigator is active
    LD A, (HL)
    CP $00
    JR Z, next_navigator_display
    
    ; Get navigator position
    LD A, (IX+0)        ; X position
    LD (temp_x), A
    LD A, (IX+1)        ; Y position
    LD (temp_y), A
    
    ; Get navigator type for display
    INC HL              ; Point to type
    LD A, (HL)          ; Load type
    ADD A, $4E          ; Base navigator character (N, O, P...)
    LD (temp_char), A
    
    ; Display navigator with attribute effects
    CALL display_entity_with_attributes
    
    DEC HL              ; Back to active flag

next_navigator_display:
    INC HL              ; Next active flag
    INC HL              ; Skip type
    INC IX              ; Next X position
    INC IX              ; Next Y position
    DJNZ display_navigator_loop
    
    RET

; Display spectral entities with dimensional effects
display_spectral_entities:
    LD B, 8             ; Maximum spectral entities
    LD HL, spectral_active_array
    LD IX, spectral_x_array
    
display_spectral_loop:
    ; Check if spectral entity is active
    LD A, (HL)
    CP $00
    JR Z, next_spectral_display
    
    ; Get spectral position
    LD A, (IX+0)        ; X position
    LD (temp_x), A
    LD A, (IX+1)        ; Y position
    LD (temp_y), A
    
    ; Get spectral type for display
    INC HL              ; Point to type
    LD A, (HL)          ; Load type
    ADD A, $52          ; Base spectral character (S, T, U...)
    LD (temp_char), A
    
    ; Display spectral entity with dimensional effects
    CALL display_entity_with_dimensional_attributes
    
    DEC HL              ; Back to active flag

next_spectral_display:
    INC HL              ; Next active flag
    INC HL              ; Skip type
    INC HL              ; Skip phase
    INC IX              ; Next X position
    INC IX              ; Next Y position
    DJNZ display_spectral_loop
    
    RET

; Display entity with special attribute effects
display_entity_with_attributes:
    ; Calculate screen position
    LD A, (temp_y)      ; Y position
    LD H, A             ; H = Y
    LD A, (temp_x)      ; X position
    LD L, A             ; L = X
    
    ; Convert to screen address
    CALL calculate_screen_address
    
    ; Display character
    LD A, (temp_char)
    LD (HL), A
    
    ; Set attribute with entity-specific effects
    CALL calculate_attribute_address
    LD A, (temp_char)   ; Use character for color variation
    AND $07             ; Mask to valid colors
    ADD A, $40          ; Bright colors
    LD (HL), A          ; Set attribute
    
    RET

; Data arrays for multi-entity management
navigator_x_array:              DEFS 6      ; Navigator X positions
navigator_y_array:              DEFS 6      ; Navigator Y positions
navigator_active_array:         DEFS 6      ; Navigator active flags
navigator_type_array:           DEFS 6      ; Navigator type IDs
navigator_velocity_x_array:     DEFS 6      ; Navigator X velocities
navigator_velocity_y_array:     DEFS 6      ; Navigator Y velocities

spectral_x_array:               DEFS 8      ; Spectral entity X positions
spectral_y_array:               DEFS 8      ; Spectral entity Y positions
spectral_active_array:          DEFS 8      ; Spectral entity active flags
spectral_type_array:            DEFS 8      ; Spectral entity type IDs
spectral_phase_array:           DEFS 8      ; Spectral dimensional phases

; Entity management variables
active_navigator_count:         DEFB 0      ; Current active navigator count
active_spectral_count:          DEFB 0      ; Current active spectral count
active_attribute_count:         DEFB 0      ; Current active attribute count
max_navigator_count:            DEFB 0      ; Maximum navigator limit
max_spectral_count:             DEFB 0      ; Maximum spectral limit
max_attribute_count:            DEFB 0      ; Maximum attribute limit
spawn_timer:                    DEFB 0      ; Entity spawn timer
dimensional_spawn_counter:      DEFB 0      ; Spawn position counter
target_navigator_x:             DEFB 0      ; Target X for AI
target_navigator_y:             DEFB 0      ; Target Y for AI
temp_x:                         DEFB 0      ; Temporary X coordinate
temp_y:                         DEFB 0      ; Temporary Y coordinate
temp_char:                      DEFB 0      ; Temporary character

; Data structure pointers
navigator_array_pointer:        DEFW 0      ; Pointer to navigator data
spectral_array_pointer:         DEFW 0      ; Pointer to spectral data
navigator_position_data:        DEFS 24     ; Navigator position storage
spectral_entity_data:           DEFS 32     ; Spectral entity storage
expanded_maze_pattern:          DEFS 768    ; Expanded maze data

Your Dimensional Achievement

Congratulations! You’ve transformed your Prism Quest into a multi-dimensional entity ecosystem! Your multiplication enhancement adds:

Multi-Entity Systems

• Navigator Arrays: Efficient management of up to 6 dimensional navigators
• Spectral Entities: 8 dimensional beings with unique behaviors and AI
• Memory Optimization: ZX Spectrum-efficient entity management within 48KB constraints
• Dynamic Spawning: Intelligent entity generation respecting memory limitations

Advanced Data Structures

• Memory-Efficient Arrays: Structured data organization for multiple entity types
• Attribute-Based Visualization: Creative use of Spectrum’s attribute system for entity differentiation
• Dimensional Behavior Systems: AI patterns optimized for memory constraints
• Collision Detection: Efficient multi-entity interaction checking

Sophisticated Entity Behaviors

• Wandering Spectrals: Random-like movement creating dynamic dimensional atmosphere
• Chasing Spectrals: AI entities that pursue navigators through dimensional space
• Dimensional Guardians: Territory-defending entities with zone-based behavior
• Navigator Multiplication: Multiple player-like entities with independent movement

Technical Mastery Gained

ZX Spectrum Memory Optimization

You’ve learned to work within 48KB constraints while creating rich experiences:

• Efficient Data Structures: Compact arrays that maximize entity count
• Memory-Conscious Design: Entity limits that maintain smooth performance
• Attribute System Mastery: Creative visualization using color attributes
• Boundary Management: Safe memory access and efficient entity processing

Array Programming Excellence

Your multi-entity system demonstrates professional array usage:

• Structured Entity Management: Clean separation of position, state, and behavior data
• Efficient Iteration: Optimized loops for processing multiple entities
• Dynamic Allocation: Smart spawning and management of active entities
• Performance Optimization: Frame-rate considerations with memory constraints

Take It Further

Your dimensional multiplication system enables amazing future enhancements:

• Dimensional Portals: Entities that can travel between different dimensional planes
• Entity Evolution: Spectral beings that change type based on interactions
• Collective Intelligence: Groups of entities that coordinate behaviors
• Dimensional Ecosystems: Complex entity relationships and environmental interactions
• Memory Banking: Advanced techniques for handling even more entities

You’ve mastered arrays and memory management through creative dimensional entity programming, preparing your world for the epic multi-dimensional adventures coming in Tiers 2-4!