Stabilize api yikes
This commit is contained in:
parent
0f9c9a0804
commit
57dfc76588
86
README.md
86
README.md
|
@ -1,97 +1,31 @@
|
||||||
# teeworlds-client
|
# teeworlds-client
|
||||||
A teeworlds 0.7 client library written in ruby
|
A teeworlds 0.7 client library written in ruby
|
||||||
|
|
||||||
## Simple chat printing client
|
## Sample
|
||||||
|
|
||||||
|
Here a simple sample usage of the library.
|
||||||
|
Connecting a client to localhost on port 8303.
|
||||||
|
And printing out every chat message the server sends.
|
||||||
|
Also properly disconnect when the program is killed gracefully.
|
||||||
|
|
||||||
|
For more sample usages checkout the [examples/](examples/) folder.
|
||||||
|
|
||||||
```ruby
|
```ruby
|
||||||
require_relative 'lib/teeworlds-client'
|
require_relative 'lib/teeworlds-client'
|
||||||
|
|
||||||
client = TeeworldsClient.new(verbose: false)
|
client = TeeworldsClient.new(verbose: false)
|
||||||
|
|
||||||
# print all incoming chat messages
|
|
||||||
# the variable `msg` holds an instance of the class `ChatMessage` which has the following fields
|
|
||||||
#
|
|
||||||
# msg.mode
|
|
||||||
# msg.client_id
|
|
||||||
# msg.target_id
|
|
||||||
# msg.message
|
|
||||||
# msg.author.id
|
|
||||||
# msg.author.team
|
|
||||||
# msg.author.name
|
|
||||||
# msg.author.clan
|
|
||||||
client.hook_chat do |msg|
|
client.hook_chat do |msg|
|
||||||
puts "[chat] #{msg}"
|
puts "[chat] #{msg}"
|
||||||
end
|
end
|
||||||
|
|
||||||
# properly disconnect on ctrl+c
|
|
||||||
Signal.trap('INT') do
|
Signal.trap('INT') do
|
||||||
client.disconnect
|
client.disconnect
|
||||||
end
|
end
|
||||||
|
|
||||||
# connect to localhost and block the current thread
|
|
||||||
client.connect('localhost', 8303, detach: false)
|
client.connect('localhost', 8303, detach: false)
|
||||||
```
|
```
|
||||||
|
|
||||||
## Print all network traffic
|
## Documentation
|
||||||
|
|
||||||
```ruby
|
Checkout [docs/01.md](docs/01.md) for a full library documentation.
|
||||||
require_relative 'lib/teeworlds-client'
|
|
||||||
|
|
||||||
client = TeeworldsClient.new(verbose: true)
|
|
||||||
|
|
||||||
# connect to localhost and block the current thread
|
|
||||||
client.connect('localhost', 8303, detach: false)
|
|
||||||
```
|
|
||||||
|
|
||||||
## Detach client (do not block the main thread)
|
|
||||||
|
|
||||||
```ruby
|
|
||||||
require_relative 'lib/teeworlds-client'
|
|
||||||
|
|
||||||
client = TeeworldsClient.new(verbose: true)
|
|
||||||
|
|
||||||
# connect to localhost and detach a background thread
|
|
||||||
client.connect('localhost', 8303, detach: true)
|
|
||||||
|
|
||||||
loop do
|
|
||||||
# send a chat message every 5 seconds
|
|
||||||
sleep 5
|
|
||||||
client.send_chat('hello friends!')
|
|
||||||
end
|
|
||||||
```
|
|
||||||
|
|
||||||
## Set custom skin and other player infos
|
|
||||||
|
|
||||||
```ruby
|
|
||||||
require_relative 'lib/teeworlds-client'
|
|
||||||
|
|
||||||
client = TeeworldsClient.new(verbose: true)
|
|
||||||
|
|
||||||
# all keys are optional
|
|
||||||
# if not provided they will fall back to the default value
|
|
||||||
client.set_startinfo(
|
|
||||||
name: "ruby gamer",
|
|
||||||
clan: "",
|
|
||||||
country: -1,
|
|
||||||
body: "spiky",
|
|
||||||
marking: "duodonny",
|
|
||||||
decoration: "",
|
|
||||||
hands: "standard",
|
|
||||||
feet: "standard",
|
|
||||||
eyes: "standard",
|
|
||||||
custom_color_body: 0,
|
|
||||||
custom_color_marking: 0,
|
|
||||||
custom_color_decoration: 0,
|
|
||||||
custom_color_hands: 0,
|
|
||||||
custom_color_feet: 0,
|
|
||||||
custom_color_eyes: 0,
|
|
||||||
color_body: 0,
|
|
||||||
color_marking: 0,
|
|
||||||
color_decoration: 0,
|
|
||||||
color_hands: 0,
|
|
||||||
color_feet: 0,
|
|
||||||
color_eyes: 0)
|
|
||||||
|
|
||||||
# connect to localhost and block the current thread
|
|
||||||
client.connect('localhost', 8303, detach: false)
|
|
||||||
```
|
|
||||||
|
|
87
docs/01.md
Normal file
87
docs/01.md
Normal file
|
@ -0,0 +1,87 @@
|
||||||
|
# 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)]
|
||||||
|
|
||||||
|
## TeeworldsClient
|
||||||
|
|
||||||
|
### #hook_chat(&block)
|
||||||
|
|
||||||
|
**Parameter: block [Block]**
|
||||||
|
|
||||||
|
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.hook_chat do |msg|
|
||||||
|
puts "[chat] #{msg}"
|
||||||
|
end
|
||||||
|
|
||||||
|
client.connect('localhost', 8303, detach: true)
|
||||||
|
```
|
||||||
|
|
||||||
|
### 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!')
|
||||||
|
```
|
28
examples/01_chat_logger.rb
Normal file
28
examples/01_chat_logger.rb
Normal file
|
@ -0,0 +1,28 @@
|
||||||
|
# Print all incoming chat messages to stdout
|
||||||
|
|
||||||
|
require_relative 'lib/teeworlds-client'
|
||||||
|
|
||||||
|
client = TeeworldsClient.new(verbose: false)
|
||||||
|
|
||||||
|
# print all incoming chat messages
|
||||||
|
# the variable `msg` holds an instance of the class `ChatMessage` which has the following fields
|
||||||
|
#
|
||||||
|
# msg.mode
|
||||||
|
# msg.client_id
|
||||||
|
# msg.target_id
|
||||||
|
# msg.message
|
||||||
|
# msg.author.id
|
||||||
|
# msg.author.team
|
||||||
|
# msg.author.name
|
||||||
|
# msg.author.clan
|
||||||
|
client.hook_chat do |msg|
|
||||||
|
puts "[chat] #{msg}"
|
||||||
|
end
|
||||||
|
|
||||||
|
# properly disconnect on ctrl+c
|
||||||
|
Signal.trap('INT') do
|
||||||
|
client.disconnect
|
||||||
|
end
|
||||||
|
|
||||||
|
# connect to localhost and block the current thread
|
||||||
|
client.connect('localhost', 8303, detach: false)
|
8
examples/02_packet_debugger.rb
Normal file
8
examples/02_packet_debugger.rb
Normal file
|
@ -0,0 +1,8 @@
|
||||||
|
# Prints out all network traffic
|
||||||
|
|
||||||
|
require_relative 'lib/teeworlds-client'
|
||||||
|
|
||||||
|
client = TeeworldsClient.new(verbose: true)
|
||||||
|
|
||||||
|
# connect to localhost and block the current thread
|
||||||
|
client.connect('localhost', 8303, detach: false)
|
14
examples/03_send_chat.rb
Normal file
14
examples/03_send_chat.rb
Normal file
|
@ -0,0 +1,14 @@
|
||||||
|
# Chat spamming client
|
||||||
|
|
||||||
|
require_relative 'lib/teeworlds-client'
|
||||||
|
|
||||||
|
client = TeeworldsClient.new(verbose: true)
|
||||||
|
|
||||||
|
# connect to localhost and detach a background thread
|
||||||
|
client.connect('localhost', 8303, detach: true)
|
||||||
|
|
||||||
|
loop do
|
||||||
|
# send a chat message every 5 seconds
|
||||||
|
sleep 5
|
||||||
|
client.send_chat('hello friends!')
|
||||||
|
end
|
33
examples/04_player_infos.rb
Normal file
33
examples/04_player_infos.rb
Normal file
|
@ -0,0 +1,33 @@
|
||||||
|
# Set custom skin and other player infos
|
||||||
|
|
||||||
|
require_relative 'lib/teeworlds-client'
|
||||||
|
|
||||||
|
client = TeeworldsClient.new(verbose: true)
|
||||||
|
|
||||||
|
# all keys are optional
|
||||||
|
# if not provided they will fall back to the default value
|
||||||
|
client.set_startinfo(
|
||||||
|
name: "ruby gamer",
|
||||||
|
clan: "",
|
||||||
|
country: -1,
|
||||||
|
body: "spiky",
|
||||||
|
marking: "duodonny",
|
||||||
|
decoration: "",
|
||||||
|
hands: "standard",
|
||||||
|
feet: "standard",
|
||||||
|
eyes: "standard",
|
||||||
|
custom_color_body: 0,
|
||||||
|
custom_color_marking: 0,
|
||||||
|
custom_color_decoration: 0,
|
||||||
|
custom_color_hands: 0,
|
||||||
|
custom_color_feet: 0,
|
||||||
|
custom_color_eyes: 0,
|
||||||
|
color_body: 0,
|
||||||
|
color_marking: 0,
|
||||||
|
color_decoration: 0,
|
||||||
|
color_hands: 0,
|
||||||
|
color_feet: 0,
|
||||||
|
color_eyes: 0)
|
||||||
|
|
||||||
|
# connect to localhost and block the current thread
|
||||||
|
client.connect('localhost', 8303, detach: false)
|
|
@ -56,6 +56,18 @@ class TeeworldsClient
|
||||||
@hooks[:chat] = block
|
@hooks[:chat] = block
|
||||||
end
|
end
|
||||||
|
|
||||||
|
def send_chat(str)
|
||||||
|
@netbase.send_packet(
|
||||||
|
NetChunk.create_vital_header({vital: true}, 4 + str.length) +
|
||||||
|
[
|
||||||
|
pack_msg_id(NETMSGTYPE_CL_SAY),
|
||||||
|
CHAT_ALL,
|
||||||
|
64 # should use TARGET_SERVER (-1) instead of hacking 64 in here
|
||||||
|
] +
|
||||||
|
Packer.pack_str(str)
|
||||||
|
)
|
||||||
|
end
|
||||||
|
|
||||||
def connect(ip, port, options = {})
|
def connect(ip, port, options = {})
|
||||||
options[:detach] = options[:detach] || false
|
options[:detach] = options[:detach] || false
|
||||||
if options[:detach]
|
if options[:detach]
|
||||||
|
@ -202,18 +214,6 @@ class TeeworldsClient
|
||||||
(msg_id << 1) | (options[:system] ? 1 : 0)
|
(msg_id << 1) | (options[:system] ? 1 : 0)
|
||||||
end
|
end
|
||||||
|
|
||||||
def send_chat(str)
|
|
||||||
@netbase.send_packet(
|
|
||||||
NetChunk.create_vital_header({vital: true}, 4 + str.length) +
|
|
||||||
[
|
|
||||||
pack_msg_id(NETMSGTYPE_CL_SAY),
|
|
||||||
CHAT_ALL,
|
|
||||||
64 # should use TARGET_SERVER (-1) instead of hacking 64 in here
|
|
||||||
] +
|
|
||||||
Packer.pack_str(str)
|
|
||||||
)
|
|
||||||
end
|
|
||||||
|
|
||||||
def send_input
|
def send_input
|
||||||
header = [0x10, 0x0A, 01] + str_bytes(@token)
|
header = [0x10, 0x0A, 01] + str_bytes(@token)
|
||||||
random_compressed_input = [
|
random_compressed_input = [
|
||||||
|
|
Loading…
Reference in a new issue