# FLHook Client

[![Build Status](](
[![Coverage Status](](

[FLHook]( is a community-managed tool for
managing [Freelancer](<>)
game servers. Freelancer is a pretty old game that has been released in 2003 by
Microsoft, but it still has a very committed community.

FLHook allows connecting via a socket to run commands on and receive events from
a Freelancer Server. This library provides an Elixir client for that matter. You
could use it to build web-based management interfaces or ingame chat bots, for

## Use Cases

- Chat Bots
- Web-based Services
  - Character Management
  - Character Money Deposit
  - Character Cargo Deposit
- Player Tracking and Travel Journal
- Custom Cargo Missions

## Installation

The package is [available in Hex]( and
can be installed by adding `fl_hook_client` to your list of dependencies in

def deps do
    {:fl_hook_client, "~> 0.2"}

## Usage

Initiate a connection to a server (with a list of all possible options):

{:ok, client} =
    backoff_interval: 1234,
    codec: :unicode,
    connect_timeout: 2345,
    event_mode: true,
    host: "localhost",
    inet_adapter: :inet,
    name: CustomFLHookClient,
    password: "$3cret",
    port: 1920,
    recv_timeout: 3456,
    send_timeout: 4567,
    subscribers: [self()],
    tcp_adapter: :gen_tcp

Once connected, you can send commands to the server.

FLHook.Client.cmd(client, "readcharfile Player1")
# => {:ok, %FLHook.Result{lines: ["...", "..."]}}

Alternatively, you can use the tuple format for commands:

FLHook.Client.cmd(client, {"readcharfile", ["Player1"]})

Additionally, any value is accepted as command argument that implements the
`FLHook.Command` protocol.

By default, also events from the server will be sent to all subscribed
processes. You can add a subscription for the current process as follows:


You can also subscribe other processes:

pid = self()

Task.async(fn ->
  FLHook.Client.subscribe(client, pid)

Unsubscription works the same way.

The received events have the following format:

iex> flush()
%FLHook.Event{type: "launch", params: %{"system" => "Li01", "char" => "Player"}}

Generally, it is recommended to start the client as part of your supervision
tree. To do this, add a custom module using the `FLHook.Client` module.

defmodule MyApp.FLClient do
  use FLHook.Client, otp_app: :my_app

Then, add some configuration in config.exs or your environment-specific configs.

config :my_app, MyApp.FLClient,
  host: "localhost",
  port: 1920

After that, add your custom client to your application.ex.

def start(_type, _args) do
  children = [

  # ...

Voilà! You can now send commands to the same server without passing the client
process as first argument.

MyApp.FLClient.cmd(client, "readcharfile Player1")
# => {:ok, %FLHook.Result{lines: ["...", "..."]}}

## Docs

Documentation can be generated with
[ExDoc]( and published on
[HexDocs]( Once published, the docs can be found at