Playtesting Methods

Validate Your Design Through Testing

Understanding Playtesting

Interactive Playtesting Dashboard

Playtesting Implementation in Python

import json
import csv
import time
import random
from typing import Dict, List, Optional, Any, Tuple
from dataclasses import dataclass, asdict
from enum import Enum
from datetime import datetime
import statistics

class TestType(Enum):
    USABILITY = "usability"
    BALANCE = "balance"
    FUN = "fun"
    TUTORIAL = "tutorial"
    DIFFICULTY = "difficulty"
    AB_TEST = "ab_test"

@dataclass
class TesterProfile:
    """Playtester demographic information"""
    id: str
    age_group: str
    experience_level: str
    play_frequency: str
    genre_preferences: List[str]
    platform: str
    
@dataclass
class TestEvent:
    """Individual test event"""
    timestamp: float
    event_type: str
    tester_id: str
    data: Dict[str, Any]
    
@dataclass
class TestMetrics:
    """Collected test metrics"""
    completion_rate: float
    average_time: float
    error_count: int
    satisfaction_score: float
    task_success_rate: float
    engagement_score: float

class PlaytestManager:
    """Comprehensive playtesting system"""
    
    def __init__(self) -> None:
        self.session_id: Optional[str] = None
        self.test_type: TestType = TestType.USABILITY
        self.testers: List[TesterProfile] = []
        self.events: List[TestEvent] = []
        self.start_time: Optional[float] = None
        self.metrics: TestMetrics = TestMetrics(0, 0, 0, 0, 0, 0)
        
        # Data collection
        self.heatmap_data: Dict[str, int] = {}
        self.path_data: Dict[str, List[Tuple[float, float, float]]] = {}
        self.input_sequences: List[Dict[str, Any]] = []
        self.feedback_responses: List[Dict[str, Any]] = []
        
        # Analytics
        self.funnel_analysis: Dict = {}
        self.retention_data: Dict = {}
        self.engagement_metrics: Dict = {}
        
    def start_session(self, test_type: TestType, testers: List[TesterProfile]) -> None:
        """Start a new playtest session"""
        self.session_id = f"session_{datetime.now().strftime('%Y%m%d_%H%M%S')}"
        self.test_type = test_type
        self.testers = testers
        self.start_time = time.time()
        self.events = []
        
        print(f"Starting {test_type.value} test with {len(testers)} testers")
        
        # Log session start
        self.log_event("session_start", "system", {
            "test_type": test_type.value,
            "tester_count": len(testers)
        })
    
    def log_event(self, event_type: str, tester_id: str, data: Dict[str, Any]) -> None:
        """Log a test event"""
        event = TestEvent(
            timestamp=time.time() - self.start_time if self.start_time else 0,
            event_type=event_type,
            tester_id=tester_id,
            data=data
        )
        self.events.append(event)
    
    def track_position(self, tester_id: str, x: float, y: float) -> None:
        """Track tester position for heatmap"""
        grid_x = int(x / 20) * 20
        grid_y = int(y / 20) * 20
        key = f"{grid_x},{grid_y}"
        
        if key not in self.heatmap_data:
            self.heatmap_data[key] = 0
        self.heatmap_data[key] += 1
        
        # Track path
        if tester_id not in self.path_data:
            self.path_data[tester_id] = []
        self.path_data[tester_id].append((x, y, time.time()))
    
    def track_input(self, tester_id: str, input_type: str, data: Dict[str, Any]) -> None:
        """Track user input"""
        self.input_sequences.append({
            'tester_id': tester_id,
            'type': input_type,
            'data': data,
            'timestamp': time.time() - self.start_time
        })
        
        self.log_event(f"input_{input_type}", tester_id, data)
    
    def collect_feedback(self, tester_id: str, feedback_type: str, response: Any) -> None:
        """Collect tester feedback"""
        self.feedback_responses.append({
            'tester_id': tester_id,
            'type': feedback_type,
            'response': response,
            'timestamp': time.time() - self.start_time
        })
    
    def calculate_metrics(self) -> TestMetrics:
        """Calculate test metrics"""
        if not self.events:
            return self.metrics
        
        # Completion rate
        completions = [e for e in self.events if e.event_type == 'task_complete']
        starts = [e for e in self.events if e.event_type == 'task_start']
        completion_rate = len(completions) / max(len(starts), 1)
        
        # Average time
        completion_times = [e.timestamp for e in completions]
        avg_time = statistics.mean(completion_times) if completion_times else 0
        
        # Error count
        errors = [e for e in self.events if 'error' in e.event_type]
        error_count = len(errors)
        
        # Satisfaction score (from feedback)
        satisfaction_scores = [
            f['response'] for f in self.feedback_responses 
            if f['type'] == 'satisfaction' and isinstance(f['response'], (int, float))
        ]
        satisfaction = statistics.mean(satisfaction_scores) if satisfaction_scores else 0
        
        # Task success rate
        task_successes = [e for e in self.events if e.event_type == 'task_success']
        task_attempts = [e for e in self.events if e.event_type == 'task_attempt']
        success_rate = len(task_successes) / max(len(task_attempts), 1)
        
        # Engagement score (based on interactions)
        interactions = [e for e in self.events if 'interact' in e.event_type]
        engagement = min(len(interactions) / (len(self.testers) * 10), 1.0)
        
        self.metrics = TestMetrics(
            completion_rate=completion_rate,
            average_time=avg_time,
            error_count=error_count,
            satisfaction_score=satisfaction,
            task_success_rate=success_rate,
            engagement_score=engagement
        )
        
        return self.metrics
    
    def analyze_funnel(self, stages: List[str]) -> Dict:
        """Analyze conversion funnel"""
        funnel = {}
        
        for i, stage in enumerate(stages):
            stage_events = [e for e in self.events if e.data.get('stage') == stage]
            unique_testers = set(e.tester_id for e in stage_events)
            
            funnel[stage] = {
                'count': len(unique_testers),
                'percentage': len(unique_testers) / len(self.testers) * 100 if self.testers else 0
            }
            
            if i > 0:
                prev_stage = stages[i-1]
                if prev_stage in funnel:
                    conversion = funnel[stage]['count'] / max(funnel[prev_stage]['count'], 1) * 100
                    funnel[stage]['conversion_from_previous'] = conversion
        
        self.funnel_analysis = funnel
        return funnel
    
    def generate_heatmap(self) -> Dict[str, float]:
        """Generate heatmap visualization data"""
        max_intensity = max(self.heatmap_data.values()) if self.heatmap_data else 1
        
        normalized_heatmap = {
            key: value / max_intensity 
            for key, value in self.heatmap_data.items()
        }
        
        return normalized_heatmap
    
    def identify_pain_points(self) -> List[Dict[str, Any]]:
        """Identify areas where testers struggle"""
        pain_points = []
        
        # Find high error areas
        error_events = [e for e in self.events if 'error' in e.event_type]
        error_locations = {}
        
        for event in error_events:
            if 'x' in event.data and 'y' in event.data:
                loc = (event.data['x'], event.data['y'])
                if loc not in error_locations:
                    error_locations[loc] = 0
                error_locations[loc] += 1
        
        # Find areas with repeated attempts
        attempt_events = [e for e in self.events if e.event_type == 'task_attempt']
        repeated_attempts = {}
        
        for event in attempt_events:
            task = event.data.get('task')
            if task:
                if task not in repeated_attempts:
                    repeated_attempts[task] = []
                repeated_attempts[task].append(event.tester_id)
        
        # Compile pain points
        for task, testers in repeated_attempts.items():
            if len(testers) > len(set(testers)):  # Multiple attempts by same tester
                pain_points.append({
                    'type': 'repeated_attempts',
                    'task': task,
                    'severity': len(testers) / len(self.testers)
                })
        
        for loc, count in error_locations.items():
            if count > len(self.testers) * 0.3:  # 30% threshold
                pain_points.append({
                    'type': 'error_hotspot',
                    'location': loc,
                    'severity': count / len(self.testers)
                })
        
        return pain_points
    
    def export_data(self, format: str = 'json') -> str:
        """Export test data"""
        data = {
            'session_id': self.session_id,
            'test_type': self.test_type.value,
            'duration': time.time() - self.start_time if self.start_time else 0,
            'tester_count': len(self.testers),
            'metrics': asdict(self.calculate_metrics()),
            'events_count': len(self.events),
            'feedback_count': len(self.feedback_responses),
            'pain_points': self.identify_pain_points()
        }
        
        if format == 'json':
            return json.dumps(data, indent=2)
        elif format == 'csv':
            # Flatten for CSV
            rows = []
            for event in self.events:
                row = {
                    'timestamp': event.timestamp,
                    'event_type': event.event_type,
                    'tester_id': event.tester_id,
                    **event.data
                }
                rows.append(row)
            
            if rows:
                output = []
                keys = rows[0].keys()
                output.append(','.join(keys))
                for row in rows:
                    output.append(','.join(str(row.get(k, '')) for k in keys))
                return '\n'.join(output)
        
        return str(data)

class SurveyBuilder:
    """Build and manage playtest surveys"""
    
    def __init__(self) -> None:
        self.questions: List[Dict[str, Any]] = []
    
    def add_likert_scale(self, question: str, scale: int = 5) -> None:
        """Add Likert scale question"""
        self.questions.append({
            'type': 'likert',
            'question': question,
            'scale': scale,
            'options': list(range(1, scale + 1))
        })
    
    def add_multiple_choice(self, question: str, options: List[str]) -> None:
        """Add multiple choice question"""
        self.questions.append({
            'type': 'multiple_choice',
            'question': question,
            'options': options
        })
    
    def add_open_ended(self, question: str) -> None:
        """Add open-ended question"""
        self.questions.append({
            'type': 'open_ended',
            'question': question
        })
    
    def add_sus_scale(self) -> None:
        """Add System Usability Scale questions"""
        sus_questions = [
            "I think that I would like to use this game frequently",
            "I found the game unnecessarily complex",
            "I thought the game was easy to use",
            "I think that I would need support to be able to use this game",
            "I found the various functions in this game were well integrated",
            "I thought there was too much inconsistency in this game",
            "I would imagine that most people would learn to use this game very quickly",
            "I found the game very cumbersome to use",
            "I felt very confident using the game",
            "I needed to learn a lot of things before I could get going with this game"
        ]
        
        for q in sus_questions:
            self.add_likert_scale(q, 5)
    
    def calculate_sus_score(self, responses: List[int]) -> float:
        """Calculate SUS score from responses"""
        if len(responses) != 10:
            return 0
        
        score = 0
        for i, response in enumerate(responses):
            if i % 2 == 0:  # Odd questions (1, 3, 5, 7, 9)
                score += response - 1
            else:  # Even questions (2, 4, 6, 8, 10)
                score += 5 - response
        
        return score * 2.5  # Scale to 0-100

class ABTestAnalyzer:
    """Analyze A/B test results"""
    
    def __init__(self) -> None:
        self.variants: Dict[str, List[float]] = {}
        
    def add_variant(self, name: str, data: List[float]) -> None:
        """Add variant data"""
        self.variants[name] = data
    
    def calculate_significance(self, variant_a: str, variant_b: str, 
                              confidence: float = 0.95) -> Dict[str, Any]:
        """Calculate statistical significance"""
        import scipy.stats as stats
        
        data_a = self.variants.get(variant_a, [])
        data_b = self.variants.get(variant_b, [])
        
        if not data_a or not data_b:
            return {'significant': False, 'message': 'Insufficient data'}
        
        # Perform t-test
        t_stat, p_value = stats.ttest_ind(data_a, data_b)
        
        # Calculate effect size (Cohen's d)
        mean_a = statistics.mean(data_a)
        mean_b = statistics.mean(data_b)
        std_a = statistics.stdev(data_a) if len(data_a) > 1 else 0
        std_b = statistics.stdev(data_b) if len(data_b) > 1 else 0
        pooled_std = ((std_a ** 2 + std_b ** 2) / 2) ** 0.5
        effect_size = (mean_a - mean_b) / pooled_std if pooled_std > 0 else 0
        
        return {
            'significant': p_value < (1 - confidence),
            'p_value': p_value,
            'effect_size': effect_size,
            'mean_a': mean_a,
            'mean_b': mean_b,
            'winner': variant_a if mean_a > mean_b else variant_b
        }

Best Practices

Key Takeaways

Congratulations!

import pygame
from collections import defaultdict

class Session:
    """Three orthogonal instrumentation channels: spatial / temporal / semantic."""
    def __init__(self):
        self.heatmap = defaultdict(int)   # (cx, cy) -> count           [SPATIAL]
        self.path = []                    # list of (x, y, t) tuples    [TEMPORAL]
        self.events = []                  # list of (t, type, data)     [SEMANTIC]
        self.start = pygame.time.get_ticks() / 1000.0
        self._frame = 0

    def tick(self, x, y):
        # spatial: per-frame grid aggregation in 40px buckets
        self.heatmap[(x // 40, y // 40)] += 1
        # temporal: 10x sub-sampled trajectory preserving order
        self._frame += 1
        if self._frame % 10 == 0:
            self.path.append((x, y, pygame.time.get_ticks() / 1000.0 - self.start))

    def log(self, event_type, data):
        # semantic: only meaningful actions
        self.events.append((pygame.time.get_ticks() / 1000.0 - self.start, event_type, data))

    def pain_points(self, threshold=20):
        # two-signal union: spatial loitering hotspots + behavioral repeated attempts
        hotspots = [(c, n) for c, n in self.heatmap.items() if n > threshold]
        repeated = sum(1 for e in self.events if e[1] == 'task_attempt')
        return hotspots, repeated

pygame.init()
SCR = pygame.display.set_mode((800, 480))
clock, font = pygame.time.Clock(), pygame.font.Font(None, 16)
session = Session()
session.log('session_start', {})
player = pygame.Rect(50, 50, 20, 20)
targets = [pygame.Rect(700, 50, 60, 60),
           pygame.Rect(50, 400, 60, 60),
           pygame.Rect(370, 210, 60, 60)]
names = ['T1: top-right', 'T2: bottom-left', 'T3: center']
current = 0
overlays = {'heatmap': True, 'path': True, 'events': True}

run = True
while run:
    dt = clock.tick(60) / 1000.0
    for ev in pygame.event.get():
        if ev.type == pygame.QUIT: run = False
        elif ev.type == pygame.KEYDOWN:
            if ev.key == pygame.K_h: overlays['heatmap'] = not overlays['heatmap']
            if ev.key == pygame.K_p: overlays['path']    = not overlays['path']
            if ev.key == pygame.K_e: overlays['events']  = not overlays['events']
            if ev.key == pygame.K_r:
                session = Session(); session.log('session_start', {}); current = 0
    keys = pygame.key.get_pressed()
    if keys[pygame.K_LEFT]  or keys[pygame.K_a]: player.x -= int(220 * dt)
    if keys[pygame.K_RIGHT] or keys[pygame.K_d]: player.x += int(220 * dt)
    if keys[pygame.K_UP]    or keys[pygame.K_w]: player.y -= int(220 * dt)
    if keys[pygame.K_DOWN]  or keys[pygame.K_s]: player.y += int(220 * dt)
    player.clamp_ip(SCR.get_rect())

    session.tick(player.centerx, player.centery)
    if current < 3 and player.colliderect(targets[current]):
        session.log('task_complete', {'task': names[current]})
        current += 1
        if current == 3:
            session.log('session_complete', {'duration': session.events[-1][0]})

    SCR.fill((20, 20, 28))
    if overlays['heatmap'] and session.heatmap:
        mx = max(session.heatmap.values())
        for (cx, cy), n in session.heatmap.items():
            a = int(min(255, n / mx * 200))
            s = pygame.Surface((40, 40), pygame.SRCALPHA); s.fill((220, 60, 60, a))
            SCR.blit(s, (cx * 40, cy * 40))
    if overlays['path'] and len(session.path) > 1:
        pygame.draw.lines(SCR, (80, 200, 240), False, [(p[0], p[1]) for p in session.path], 2)
    for i, t in enumerate(targets):
        c = (220, 220, 80) if i == current else (40, 120, 40) if i < current else (60, 80, 60)
        pygame.draw.rect(SCR, c, t, 3)
        SCR.blit(font.render(names[i], True, (220, 220, 220)), (t.x, t.y - 16))
    if overlays['events']:
        for j, e in enumerate(session.events[-15:]):
            pygame.draw.circle(SCR, (255, 220, 80), (15 + j * 16, 460), 4)
    pygame.draw.rect(SCR, (80, 220, 100), player)

    hotspots, repeated = session.pain_points(threshold=20)
    active = names[current] if current < 3 else 'DONE'
    lines = [
        "WASD/arrows = move | H/P/E = toggle heatmap/path/events | R = reset",
        f"target progress: {current}/3   active: {active}",
        f"channel A (spatial heatmap): {len(session.heatmap)} cells visited",
        f"channel B (temporal path):   {len(session.path)} samples",
        f"channel C (semantic events): {len(session.events)} events",
        f"pain-points: {len(hotspots)} loitering hotspots (>20 visits)   repeated_attempts: {repeated}",
    ]
    for i, ln in enumerate(lines):
        SCR.blit(font.render(ln, True, (240, 240, 240)), (10, 8 + i * 18))
    pygame.display.flip()
pygame.quit()