hllrcon - Hell Let Loose RCON

hllrcon is an asynchronous Python implementation of the Hell Let Loose and Hell Let Loose: Vietnam RCON protocol.
It allows you to interact with your HLL and HLL:V servers programmatically, supporting modern Python async features and robust error handling.

Features

• Full async/await support
• Command execution and response parsing
• Collection of vanilla maps, factions, weapons, and more
• Alternative interfaces for synchronous applications
• Compatible with both Hell Let Loose and Hell Let Loose: Vietnam
• Well-typed and tested

Installation

pip install hllrcon

Usage

import asyncio
from hllrcon import HLLRcon, HLLLayer


async def main():
    # Initialize client
    rcon = HLLRcon(
        host="127.0.0.1",
        port=12345,
        password="your_rcon_password",
    )

    # Send commands. The client will (re)connect for you.
    await rcon.broadcast("Hello, HLL!")
    await rcon.change_map(Layer.STALINGRAD_WARFARE_DAY)
    players = await rcon.get_players()

    # Close the connection
    rcon.disconnect()


    # Alternatively, use the context manager interface to avoid
    # having to manually disconnect.
    async with rcon.connection():
        assert rcon.is_connected() is True
        await rcon.broadcast("Hello, HLL!")


if __name__ == "__main__":
    # Run the program
    asyncio.run(main())

Above example connects to servers running the original Hell Let Loose. Use HLLVRcon to connect to a Hell Let Loose: Vietnam server instead.

import asyncio
from hllrcon import HLLVRcon, HLLVLayer


async def main():
    # Initialize client
    rcon = HLLVRcon(
        host="127.0.0.1",
        port=12345,
        password="your_rcon_password",
    )

    # Connect and change the map
    async with rcon.connection():
        await rcon.change_map(HLLVLayer.THANHHOABRIDGE_WARFARE_DAY)

if __name__ == "__main__":
    asyncio.run(main())

For integration of synchronous applications, the HLLSyncRcon and HLLVSyncRcon classes are provided.

from hllrcon.sync import SyncRcon

rcon = HLLSyncRcon(
    host="127.0.0.1",
    port=12345,
    password="your_rcon_password",
)

# Connect and send a broadcast message
with rcon.connection():
    rcon.broadcast("Hello, HLL!")

The library contains a swathe of details about in-game maps, factions, weapons, vehicles, and more. Below is just an example of what it might be used for.

from hllron import HLLWeapon

# Find a weapon by its ID
weapon_id = "COAXIAL M1919 [Stuart M5A1]"
weapon = HLLWeapon.by_id(weapon_id)

# Print out whichever vehicle seat the attacker must have been in, if any
if weapon.vehicle:
    for seat in weapon.vehicle.seats:
        if weapon in seat.weapons:
            print("This weapon belongs to the", seat.type.name, "seat")
            break

from hllrcon import HLLRcon, HLLTeam

# Get the AA Network capture zone (SMDM, 3rd sector, 2nd capture zone)
sector = Layer.STMARIEDUMONT_WARFARE_DAY.sectors[2]
capture_zone = sector.capture_zones[1]
assert capture_zone.strongpoint.name == "AA Network"

# Get the current online players
rcon = HLLRcon(...)
players = await rcon.get_players()

# Calculate each team's capture strength towards the sector
strength = {HLLTeam.ALLIES: 0, HLLTeam.AXIS: 0}
for player in players.players:
    if player.faction is None:
        continue

    if player.world_position == (0.0, 0.0, 0.0):
        # Player is dead. Note: Does not exclude players bleeding out
        continue

    # Grant 3 strength if inside the strongpoint
    if capture_zone.strongpoint.is_inside(player.world_position):
        strength[player.faction.team] += 3

    # Only grant 1 strength if inside the capture zone
    elif capture_zone.is_inside(player.world_position):
        strength[player.faction.team] += 1

# Print out the results
print("Allied cap weight:", strength[HLLTeam.ALLIES])
print("Axis cap weight:", strength[HLLTeam.AXIS])

Versioning

The Hell Let Loose franchise is constantly evolving, and game updates might alter its games' RCON interfaces in ways that are not backward-compatible. This affects any tools and libraries that depend on it, including this library and any software utilizing it.

Releases of hllrcon only guarantee compatibility with the latest version of Hell Let Loose and Hell Let Loose: Vietnam at the time of release. See the release notes of a given version for more information on what version this is.

This project uses its own versioning system similar to Pragmatic Versioning principles (i.e. GRADE.MAJOR.MINOR.PATCH). However, there are differences in the way each of the four components are defined and what they guarantee:

• GRADE - Reserved for structural changes. Likely to increase only with the release of Hell Let Loose: Vietnam.
• MAJOR - Incremented when backward-incompatible changes are released.
• MINOR - Incremented when support for the previously supported game version is dropped.
• PATCH - Incremented when backward-compatible changes are released.

When specifying hllrcon as a dependency, it is recommended to pin the MINOR version but not the PATCH version. MINOR versions are still backward-incompatible in that they require the game server to be updated. MINOR versions may be released before the game update it depends on.

License

This project is licensed under the MIT License. See LICENSE for details.