teeworlds_network/docs/01.md

# Classes

## Player

### @id [Integer]
### @local [Integer]
### @team [Integer]
### @name [String]
### @clan [String]
### @country [Integer]
### @skin_parts [Array#String]
### @skin_custom_colors [Array#Integer]
### @skin_colors [Array#Integer]

## ChatMessage

### @mode [Integer]
### @client_id [Integer]
### @target_id [Integer]
### @message [Integer]
### @author [[Player](#player)]

## Context

This class is the callback context.
When you hook into methods using a ``on_*`` method you can access its context.
This gives you the ability to read and modify the data before the default behavior processes it.
Or skip the default behavior and implement your own logic.

### #cancle

Call the ``cancle()`` on the context object to not run any default code for that event.

```ruby
client.on_map_change do |context|
  # do nothing when a map change packet comes in
  # skips the send ready packet code
  context.cancle
end
```

### @client [[TeeworldsClient](#teeworldsclient)]

Access the network client to send packets.

**Example:**

Reimplement your on on_connected logic and cancle the default one

```ruby
client.on_connected do |ctx|
  ctx.client.send_msg_startinfo
  ctx.cancle
end
```

### @data [Hash]

This hash holds all the current data. They keys might vary depending on the current context.
You can read and write those values. If you set an unused key the program will panic.

**Example:**

Here an example to see what keys you are given for a client info event.

```ruby
client = TeeworldsClient.new

client.on_client_info do |context|
  p context.keys
  # [:player, :chunk]
end
```

Here an example to modify all incoming player info to rename all player objects to yee.
Which is a bit weird but shows the power of the modding api.

```ruby
client = TeeworldsClient.new

client.on_client_info do |context|
  context.data[:player].name = 'yee'
end
```

## TeeworldsClient

### #on_chat(&block)

**Parameter: block [Block |[ChatMessage](#chatmessage)|]**

Takes a block that will be called when the client receives a chat message.
The block takes one parameter of type [ChatMessage](#chatmessage).

**Example:**

```ruby
client = TeeworldsClient.new

client.on_chat do |msg|
  puts "[chat] #{msg}"
end

client.connect('localhost', 8303, detach: true)
```
### #on_map_change(&block)

**Parameter: block [Block |[context](#context)|]**

Takes a block that will be called when the client receives a map change packet.

**Example:**

```ruby
client = TeeworldsClient.new

client.on_map_change do |context|
  puts "Got new map!"

  # skip default behavior
  # in this case do not send the ready packet
  context.cancle
end

client.connect('localhost', 8303, detach: true)
```

### #on_client_drop(&block)

**Parameter: block [Block |[context](#context)|]**

Takes a block that will be called when the client receives a client drop packet.

Context:

```ruby
[
  player: player_object,
  chunk: raw_packet_data,
  client_id: 0,
  reason: '',
  silent: false
]
```

**Example:**

```ruby
client.on_client_drop do |ctx|
  unless ctx.data[:silent]
    reason = ctx.data[:reason] ? " (#{ctx.data[:reason]})" : ''
    puts "'#{ctx.data[:player].name}' left the game#{reason}"
  end
end
```


### connect(ip, port, options)

**Parameter: ip [String]**

**Parameter: port [Integer]**

**Parameter: options [Hash] (default: {detach: false})**

Connect to given server. The option ``:detach`` decides wether the connection should run in a background thread or not.
By default no thread will be spawned. And the ``connect()`` method blocks your main thread. Meaning no line below that will be run as long as the connection is up.

If you decide to provide the option ``detach: true`` it will spawn a thread and run the connection in there. Meaning it will jump to the next line after ``connect()`` is called. So it is your responsibility to keep the program running.
If the connection happens in the last line of your program it will just quit. So you have to keep it up using a loop for example.

**Example:**

```ruby
client = TeeworldsClient.new(verbose: true)

# this will spawn a background thread
client.connect('localhost', 8303, detach: true)
# this line will be run directly after the connection

# this line will be running as long as the connection is up
client.connect('localhost', 8303, detach: false)
# this line will only be run if the connection broke
```


### send_chat(str)

**Parameter: str [String]**

Send a chat message. Takes the chat message as String.

**Example:**

```ruby
client = TeeworldsClient.new(verbose: true)

client.connect('localhost', 8303, detach: true)

client.send_chat('hello world!')
```