python-manta 1.4.5

Python interface for the Manta Dota 2 replay parser

Python Manta

Python interface for the Manta Dota 2 replay parser with 272 complete callback implementations.

Overview

Python Manta provides a comprehensive, Pythonic interface to parse modern Dota 2 replay files (.dem) using the battle-tested Manta Go library via CGO bindings. This library implements all 272 Manta callbacks with superior data coverage compared to native Go, allowing Python applications to extract detailed game data from professional and public Dota 2 matches.

Features

• 🏆 Complete Implementation: All 272 Manta callbacks implemented (100% coverage)
• 📈 Superior Data Extraction: 40% more fields than native Go implementation
• 🎮 Modern Dota 2 Support: Handles current PBDEMS2 replay format
• 🚀 High Performance: Leverages the optimized Manta Go parser via CGO
• 🐍 Pythonic API: Clean, type-hinted Python interface with Pydantic models
• 📦 Zero Dependencies: Pre-built wheels with embedded binaries - no Go installation required
• 🔧 Multi-Platform: Linux (x86_64), macOS (Intel & Apple Silicon), Windows (AMD64)
• 💬 Real-time Chat: Extract player chat messages and communication
• 📍 Location Tracking: Parse player pings, map lines, and positioning data
• 🎯 Game Events: Complete DOTA user message and network event parsing
• ⚡ Memory Safe: Proper CGO memory management with message filtering
• 🧪 Battle Tested: Validated against TI14 professional tournament replays

Quick Start

Installation

Option 1: Install from PyPI (Recommended - No Go Required!)

# Simple pip install - pre-built wheels for Linux, macOS, and Windows
pip install python-manta

Option 2: Build from Source (Requires Go)

# Clone and build
git clone https://github.com/equilibrium-coach/python-manta.git
cd python-manta
./build.sh

Quick Test: Run the simple example to verify installation:

# Update demo file path in simple_example.py, then run:
python simple_example.py

30-Second Example

from python_manta.manta_python import MantaParser

# Initialize parser
parser = MantaParser("go_wrapper/manta_wrapper.so")

# Extract chat messages from demo
result = parser.parse_universal("match.dem", "CDOTAUserMsg_ChatMessage", 10)

# Print results
for msg in result.messages:
    player = msg.data['source_player_id']
    text = msg.data['message_text']
    print(f"Player {player}: {text}")

Basic Usage (Header Parsing)

from python_manta import parse_demo_header

# Quick header parsing
header = parse_demo_header("match.dem")
print(f"Map: {header.map_name}")
print(f"Build: {header.build_num}")
print(f"Server: {header.server_name}")

Callback Subscription (New!)

from python_manta.manta_python import MantaParser

# Initialize parser with library path
parser = MantaParser("path/to/manta_wrapper.so")

# Subscribe to chat messages (get first 10)
result = parser.parse_universal("match.dem", "CDOTAUserMsg_ChatMessage", 10)

if result.success:
    print(f"Found {result.count} chat messages:")
    for msg in result.messages:
        player_id = msg.data['source_player_id']
        text = msg.data['message_text']
        print(f"Player {player_id}: {text}")

Subscribe to Multiple Callbacks

from python_manta.manta_python import MantaParser

parser = MantaParser("path/to/manta_wrapper.so")

# Subscribe to different message types
callbacks = [
    "CDOTAUserMsg_ChatMessage",    # Player chat
    "CDOTAUserMsg_LocationPing",   # Map pings  
    "CDemoFileHeader",             # Demo metadata
    "CNETMsg_Tick",                # Network ticks
    "CSVCMsg_ServerInfo"           # Server info
]

for callback_name in callbacks:
    result = parser.parse_universal("match.dem", callback_name, 5)
    
    if result.success:
        print(f"\n{callback_name}: {result.count} messages")
        for msg in result.messages:
            print(f"  Tick {msg.tick}: {msg.data}")
    else:
        print(f"❌ {callback_name}: {result.error}")

Real Example - Extract Team Communication

from python_manta.manta_python import MantaParser

def analyze_team_communication(demo_file):
    parser = MantaParser("go_wrapper/manta_wrapper.so")
    
    # Get chat messages
    chat_result = parser.parse_universal(demo_file, "CDOTAUserMsg_ChatMessage", 100)
    
    # Get location pings
    ping_result = parser.parse_universal(demo_file, "CDOTAUserMsg_LocationPing", 50)
    
    print("=== TEAM COMMUNICATION ANALYSIS ===")
    
    if chat_result.success:
        print(f"\n💬 Chat Messages ({chat_result.count}):")
        for msg in chat_result.messages:
            player = msg.data['source_player_id']
            text = msg.data['message_text']
            tick = msg.tick
            print(f"  [{tick:6}] Player {player}: '{text}'")
    
    if ping_result.success:
        print(f"\n📍 Location Pings ({ping_result.count}):")
        for msg in ping_result.messages:
            player = msg.data['player_id']  
            ping = msg.data['location_ping']
            x, y = ping['x'], ping['y']
            tick = msg.tick
            print(f"  [{tick:6}] Player {player} pinged ({x}, {y})")

# Usage
analyze_team_communication("my_match.dem")

Requirements

For End Users (pip install):

• Python: 3.8+
• System: Linux (x86_64), macOS (Intel/Apple Silicon), or Windows (AMD64)
• No Go required! Pre-built wheels include all necessary binaries

For Developers (building from source):

• Python: 3.8+
• Go: 1.19+
• System: Linux, macOS, or Windows with CGO support

Building from Source

1. Prerequisites:

   # Ensure Go and Python are installed
   go version  # Should be 1.19+
   python3 --version  # Should be 3.8+
   

2. Clone Manta dependency:

   # From the project root directory
   git clone https://github.com/dotabuff/manta.git
   

3. Build the library:

   cd python_manta
   ./build.sh
   

4. Test installation:

   python3 examples/basic_usage.py path/to/demo.dem
   

For detailed information about the wheel building process, CI/CD pipeline, and PyPI publishing, see BUILDING.md.

API Reference

MantaParser Class (Universal Parser)

class MantaParser:
    def __init__(self, library_path: str)
    def parse_universal(self, demo_file: str, callback_filter: str, max_messages: int) -> ParseResult

Parameters:

• library_path: Path to compiled manta_wrapper.so
• demo_file: Path to .dem replay file
• callback_filter: Callback name to subscribe to
• max_messages: Maximum messages to extract (limits processing time)

ParseResult Model

class ParseResult(BaseModel):
    success: bool              # Parse success status
    count: int                # Number of messages found
    messages: List[Message]   # Extracted messages
    error: Optional[str]      # Error message if parsing failed

Message Model

class Message(BaseModel):
    type: str                 # Message type (e.g., "CDOTAUserMsg_ChatMessage")
    tick: int                # Game tick when message occurred
    net_tick: int           # Network tick
    timestamp: int          # Unix timestamp
    data: Dict[str, Any]    # Message-specific data

Available Callbacks (272 Total)

Most Useful for Game Analysis:

# Communication & Social
"CDOTAUserMsg_ChatMessage"        # Player chat messages
"CDOTAUserMsg_LocationPing"       # Map pings and signals
"CDOTAUserMsg_MapLine"           # Map drawing/lines

# Game State & Events  
"CDemoFileHeader"                # Match metadata  
"CDemoFileInfo"                  # Draft picks/bans, player info
"CDOTAUserMsg_OverheadEvent"     # Damage numbers, events
"CDOTAUserMsg_UnitEvent"         # Unit actions and abilities

# Network & Technical
"CNETMsg_Tick"                   # Game tick synchronization
"CSVCMsg_ServerInfo"             # Server configuration
"CSVCMsg_GameEvent"              # Core game events

Full callback list: All 272 Manta callbacks supported. See callbacks_*.go files for complete list.

Legacy Header API

# Legacy header parsing (still supported)
def parse_demo_header(demo_file_path: str) -> HeaderInfo

class HeaderInfo(BaseModel):
    map_name: str              # Map name
    server_name: str           # Server identifier  
    client_name: str           # Client type
    # ... other header fields

Project Structure

python_manta/
├── src/python_manta/        # Python package
│   ├── __init__.py         # Package initialization
│   ├── manta_python.py     # Main Python interface
│   ├── libmanta_wrapper.so # Compiled Go library
│   └── libmanta_wrapper.h  # C header file
├── go_wrapper/             # Go CGO source
│   ├── manta_wrapper.go    # CGO wrapper implementation
│   ├── go.mod             # Go module definition
│   └── go.sum             # Go dependency checksums
├── examples/              # Usage examples
│   └── basic_usage.py     # Basic parsing example
├── tests/                 # Test suite
├── build.sh              # Build script
├── pyproject.toml        # Python package configuration
└── README.md             # This file

Supported Replay Features

✅ Fully Implemented

• 272 Complete Callbacks: All Manta callbacks implemented and tested
• Demo Messages: File headers, user commands, animation data
• DOTA User Messages: Chat, pings, map lines, overhead events, unit actions
• Network Messages: Ticks, convars, signon state
• SVC Messages: Server info, string tables, packet entities
• Entity Messages: Complete entity system integration
• Memory Management: Safe CGO operations with message limiting
• Error Handling: Comprehensive validation and error reporting
• Real Tournament Data: Tested with TI14 professional match replays

🎯 Battle-Tested Capabilities

• ✅ Player Communication: Extract all chat messages and team coordination
• ✅ Strategic Analysis: Location pings, map drawings, tactical signals
• ✅ Game Metadata: Complete match information, server details, build data
• ✅ Network Analysis: Tick progression, packet timing, connection state
• ✅ Professional Replays: Parse tournament-grade SourceTV demos
• ✅ Data Integrity: Verified against native Go Manta implementation

📊 Comparison with Native Go Manta

Feature	Python Manta	Native Go
Callback Coverage	272/272 (100%)	272/272 (100%)
Data Fields Extracted	Enhanced (+40% more)	Standard
CDemoFileHeader Fields	14 fields	10 fields
CSVCMsg_ServerInfo Fields	15 fields	13 fields
Session Configuration	Complete	Limited
Version Metadata	Full GUIDs	Basic
Binary Manifest Data	Available	Not extracted

Development Status

This project is production-ready and actively used for professional Dota 2 analysis.

• Phase 1: ✅ Complete (Header parsing)
• Phase 2: ✅ Complete (272 callback implementation)
• Phase 3: ✅ Complete (Real tournament data validation)
• Phase 4: 🚀 Active Development (Advanced game analysis tools)

Contributing

Contributions welcome! This library is part of a larger Dota 2 analysis ecosystem.

License

MIT License - see LICENSE file for details.

Acknowledgments

• Manta - The excellent Go replay parser this library wraps
• Dotabuff - For maintaining the Manta parser
• Valve Corporation - For Dota 2 and the replay format