Film Parser 2

A Kotlin library for parsing Myth II film files and extracting complete game information.

Features

• Parse complete Myth II film files
• Extract game options, player information, plugins, and commands
• Clean API for both Kotlin and Java developers
• Comprehensive documentation with KDoc
• No complex internal data structures exposed

Usage

Kotlin

import net.bagrada.filmparser2.FilmParser

val parser = FilmParser()
val film = parser.parse("path/to/film.m2r")

// Basic film information
println("Film: ${film.name}")
println("Map: ${film.mapName}")
println("Players: ${film.players.size}")

// Game options
val options = film.gameOptions
println("Game Type: ${options.gameType}")
println("Time Limit: ${options.timeLimit} seconds")
println("Cooperative: ${options.isCooperative}")

// Player information
for (player in film.players) {
    println("Player: ${player.name} (Team: ${player.teamName})")
    println("  Team Index: ${player.teamIndex}")
    println("  Player ID: ${player.playerId}")
    println("  Game Version: ${player.gameVersion}")
    println("  Checked In: ${player.isCheckedIn}")
}

// Plugins
for (plugin in film.plugins) {
    println("Plugin: ${plugin.name}")
    println("  URL: ${plugin.url}")
    println("  Checksum: ${plugin.checksum}")
}

// Chat messages
val chatMessages = film.getChatMessages()
for (message in chatMessages) {
    println("${message.playerName}: ${message.message}")
}

// Players by team
val playersByTeam = film.getPlayersByTeam()
for ((teamIndex, teamPlayers) in playersByTeam) {
    println("Team $teamIndex: ${teamPlayers.map { it.name }}")
}

Java

import net.bagrada.filmparser2.FilmParser;
import net.bagrada.filmparser2.FilmInfo;
import net.bagrada.filmparser2.PlayerInfo;
import net.bagrada.filmparser2.GameOptionsInfo;
import net.bagrada.filmparser2.PluginInfo;

FilmParser parser = new FilmParser();
FilmInfo film = parser.parse("path/to/film.m2r");

// Basic film information
System.out.println("Film: " + film.getName());
System.out.println("Map: " + film.getMapName());
System.out.println("Players: " + film.getPlayers().size());

// Game options
GameOptionsInfo options = film.getGameOptions();
System.out.println("Game Type: " + options.getGameType());
System.out.println("Time Limit: " + options.getTimeLimit() + " seconds");
System.out.println("Cooperative: " + options.isCooperative());

// Player information
for (PlayerInfo player : film.getPlayers()) {
    System.out.println("Player: " + player.getName() + " (Team: " + player.getTeamName() + ")");
    System.out.println("  Team Index: " + player.getTeamIndex());
    System.out.println("  Player ID: " + player.getPlayerId());
    System.out.println("  Game Version: " + player.getGameVersion());
    System.out.println("  Checked In: " + player.isCheckedIn());
}

// Plugins
for (PluginInfo plugin : film.getPlugins()) {
    System.out.println("Plugin: " + plugin.getName());
    System.out.println("  URL: " + plugin.getUrl());
    System.out.println("  Checksum: " + plugin.getChecksum());
}

// Chat messages
List<ChatMessage> chatMessages = film.getChatMessages();
for (ChatMessage message : chatMessages) {
    System.out.println(message.getPlayerName() + ": " + message.getMessage());
}

API Reference

FilmParser

Main entry point for parsing film files.

• parse(filePath: String): FilmInfo - Parse a film file from path
• parse(source: BufferedSource): FilmInfo - Parse a film from buffered source

FilmInfo

Complete film information with the following properties:

• name: String - Film name
• mapName: String - Map/scenario name
• gameOptions: GameOptionsInfo - Game configuration
• plugins: List<PluginInfo> - List of plugins used
• players: List<PlayerInfo> - List of players
• commands: List<GameCommandInfo> - List of game commands

Methods:

• getChatMessages(): List<ChatMessage> - Extract chat messages with player info
• getPlayersByTeam(): Map<Int, List<PlayerInfo>> - Group players by team

GameOptionsInfo

Game configuration and settings:

• gameType: String - Game type (Body Count, Capture the Flag, etc.)
• scoring: Int - Scoring system
• timeLimit: Int - Game time limit in seconds
• planningTime: Int - Planning time limit in seconds
• difficulty: Int - Game difficulty level
• maxPlayers: Int - Maximum number of players
• maxTeams: Int - Maximum number of teams
• randomSeed: Long - Random seed used
• isCooperative: Boolean - Whether cooperative game
• allowTeams: Boolean - Whether teams allowed
• allowUnitTrading: Boolean - Whether unit trading allowed
• allowVeterans: Boolean - Whether veterans allowed
• allowAlliances: Boolean - Whether alliances allowed
• overheadMap: Boolean - Whether overhead map enabled
• deathmatch: Boolean - Whether deathmatch game
• vtfl: Boolean - Whether VTFL enabled
• antiClump: Boolean - Whether anti-clumping enabled

PlayerInfo

Player information:

• name: String - Player's display name
• teamName: String - Player's team name
• teamIndex: Int - Team index (0-based)
• playerId: Long - Unique player identifier
• metaserverUserId: Long - Metaserver user ID
• gameVersion: Int - Game version
• gameBuild: Int - Build number
• isCheckedIn: Boolean - Whether player checked in
• isTeamLocked: Boolean - Whether player's team locked
• primaryColor: ByteArray - Primary color as RGB bytes
• secondaryColor: ByteArray - Secondary color as RGB bytes

PluginInfo

Plugin information:

• name: String - Plugin name
• url: String - Plugin download URL
• checksum: String - Plugin checksum as hex string

GameCommandInfo

Game command information:

• type: String - Command type (CHAT, MOVE, ATTACK, etc.)
• senderId: Int - ID of player who sent command
• tic: Int - Game tick when command executed
• data: String - Additional command data

ChatMessage

Chat message with context:

• playerName: String - Name of player who sent message
• message: String - Chat message content
• timestamp: Int - Game tick when message sent

Dependencies

• Kotlin 2.2.0+
• Okio 3.14.0+
• Koin 4.0.3+ (for dependency injection)

Building

./gradlew build

Publishing to Maven Local

./gradlew publishToMavenLocal

Integration with Maven Projects

Add to your pom.xml:

<dependency>
    <groupId>net.bagrada</groupId>
    <artifactId>film-parser-2</artifactId>
    <version>1.0-SNAPSHOT</version>
</dependency>

Examples

See JavaExample.java for a complete Java example demonstrating all features of the API.