lugo4go

package module
v3.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 9, 2024 License: GPL-3.0 Imports: 20 Imported by: 0

README

Lugo4Go - A Lugo Bots Client

Build Status GoDoc Go Report Card

Lugo4Go is a Go implementation of a client player for Lugo game.

It is not a bot that plays the game, it is only the client for the game server.

This client implements a brainless player in the game. So, this library implements many methods that does not affect the player intelligence/behaviour/decisions. It is meant to reduce the developer concerns on communication, protocols, attributes, etc.

Using this client, you just need to implement the Artificial Intelligence of your player and some other few methods to support your strategy (see the project The Dummies as an example).

Documentation

(usage examples below)

Requirements
Installation
git get https://github.com/lugobots/lugo4go.git
Usage

There are two ways to use Lugo4Go client:

See example

Lugo4Go PlayAsBot implements a very basic logic to reduce the code boilerplate. This client will wrap most repetitive code that handles the raw data got by the bot and will identify the player state.

The Bot interface requires the methods to handle each player state based on the ball possession.


type Bot struct {
	
}

// OnDisputing is called when no one has the ball possession
func (b *Bot) OnDisputing(ctx context.Context, sender lugo4go.TurnOrdersSender, snapshot *proto.GameSnapshot) error {
	// the magic code comes here
	return ...
}

// OnDefending is called when an opponent player has the ball possession
func (b *Bot) OnDefending(ctx context.Context, sender lugo4go.TurnOrdersSender, snapshot *proto.GameSnapshot) error {
	// the magic code comes here
	return ...
}

// OnHolding is called when this bot has the ball possession
func (b *Bot) OnHolding(ctx context.Context, sender lugo4go.TurnOrdersSender, snapshot *proto.GameSnapshot) error {
	// the magic code comes here
	return ...
}

// OnSupporting is called when a teammate player has the ball possession
func (b *Bot) OnSupporting(ctx context.Context, sender lugo4go.TurnOrdersSender, snapshot *proto.GameSnapshot) error {
	// the magic code comes here
	return ...
}

// AsGoalkeeper is only called when this bot is the goalkeeper (number 1). This method is called on every turn,
// and the player state is passed at the last parameter.
func (b *Bot) AsGoalkeeper(ctx context.Context, sender lugo4go.TurnOrdersSender, snapshot *proto.GameSnapshot, state lugo4go.PlayerState) error {
	// the magic code comes here
	return ...
}
Implementing the turn handler (a little more work)

See example

If you rather to handle everything on your side, you only need to implement the TurnHandler interface.

The TurnHandler will receive the turn context and the turn snapshot for each turn.

Your bot will need a lugo4go.OrderSender to send the orders back to the Game Server during each turn.


type Bot struct {
    OrderSender lugo4go.OrderSender
}

func (b *Bot) Handle(ctx context.Context, snapshot *proto.GameSnapshot) {
	// the magic code comes here
	resp, err := b.OrderSender.Send(ctx, snapshot.Turn, orders, "")
}

Kick-start

  1. Copy one of the examples from the example directory as a new Golang project.

  2. Run the game server using the command

    docker run -p 8080:8080  lugobots/server:v1.1 play --dev-mode

  3. Now you will need to start your team processes. Each team must have 11 process (one for each player).

    Option A: You may start your team players manually executing the command go run main.go -team=home -number=[1-11] eleven times.

    or

    Option B: You can use the script in examples directory to do this automatically for you: ./play.sh home

  4. And, if your have not started the away team, you may do the same for the other team.

    You play against your own team repeating the last step, but in the away side:

    ./play.sh away
Next steps

As you may have noticed, the bot player in the example directory does not play well. Now, you may start your bot by implementing its behaviour.

Deploying you bots

After developing your bot, you may share it with other developers.

Please find the instructions for uploading your bot on lugobots.dev.

There is a Dockerfile template in the example directory to guide you how to create a container.

Field Library

There are a many things that you will repeatedly need to do on your bot code, e.g. getting your bot position, creating a move/kick/catch order, finding your teammates positions, etc.

The Field library brings a collection of functions that will help you get that data from the game snapshot:

Examples (see all functions on the documentation page)


myTeamGoal := field.GetTeamsGoal(proto.Team_HOME)

moveOrder, err := field.MakeOrderMoveMaxSpeed(*me.Position, myTeamGoal)
Mapper and Region

The Field library also provides a quite useful pair: the Mapper interface and Region struct.

The Mapper

Mapper slices the field in columns and rows, so your bot does not have to care about precise coordinates or the team side. The mapper will automatically translate the map position to the bot side.

And you may define how many columns/rows your field will be divided into.


// let's create a map 10x5 
fieldMapper, err := field.NewMapper(10, 5, proto.Team_HOME)

aRegion, err := fieldMapper.GetRegion(2, 4)
The Region

The Mapper will slice the field into Regions. The Region struct helps your bot to move over the field without caring about coordinates or team side.


regionInFrontOfMe _:= aRegion.Front()

moveOrder, err_ := field.MakeOrderMoveMaxSpeed(*me.Position, regionInFrontOfMe.Center())

Documentation

Index

Constants

View Source 
const (
	EnvVarBotTeam         = "BOT_TEAM"
	EnvVarBotNumber       = "BOT_NUMBER"
	EnvVarBotGrpcUrl      = "BOT_GRPC_URL"
	EnvVarBotGrpcInsecure = "BOT_GRPC_INSECURE"
	EnvVarBotToken        = "BOT_TOKEN"
)
View Source 
const (
	DefaultFieldMapCols = 16
	DefaultFieldMapRows = 8
)
View Source 
const ProtocolVersion = "0.0.1"

ProtocolVersion defines the current game protocol

Variables

View Source 
var (
	// ErrGRPCConnectionClosed identifies when the error returned is cased by the connection has been closed
	ErrGRPCConnectionClosed = errors.New("grpc connection closed by the server")

	// ErrGRPCConnectionLost identifies that something unexpected broke the gRPC connection
	ErrGRPCConnectionLost = errors.New("grpc stream error")
)
View Source 
var (
	ErrNilSnapshot    = errors.New("invalid snapshot state (nil)")
	ErrPlayerNotFound = errors.New("player not found in the game snapshot")
	ErrNoBall         = errors.New("no ball found in the snapshot")
)
View Source 
var DefaultInitialPositions = map[int]struct {
	Col int
	Row int
}{
	2:  {Col: 1, Row: 2},
	3:  {Col: 1, Row: 3},
	4:  {Col: 1, Row: 4},
	5:  {Col: 1, Row: 5},
	6:  {Col: 4, Row: 1},
	7:  {Col: 4, Row: 3},
	8:  {Col: 4, Row: 4},
	9:  {Col: 4, Row: 6},
	10: {Col: 6, Row: 3},
	11: {Col: 6, Row: 4},
}

Functions

func DefaultLogger 

func DefaultLogger(config Config) *zap.SugaredLogger

DefaultLogger creates a logger that is compatible with the lugo4go.rawBot expected logger. The bots are NOT obligated to use this logger though. You may implement your own logger.

Types

type Bot 

type Bot interface {
	// OnDisputing is called when no one has the ball possession
	OnDisputing(ctx context.Context, inspector SnapshotInspector) ([]proto.PlayerOrder, string, error)
	// OnDefending is called when an opponent player has the ball possession
	OnDefending(ctx context.Context, inspector SnapshotInspector) ([]proto.PlayerOrder, string, error)
	// OnHolding is called when this bot has the ball possession
	OnHolding(ctx context.Context, inspector SnapshotInspector) ([]proto.PlayerOrder, string, error)
	// OnSupporting is called when a teammate player has the ball possession
	OnSupporting(ctx context.Context, inspector SnapshotInspector) ([]proto.PlayerOrder, string, error)
	// AsGoalkeeper is only called when this bot is the goalkeeper (number 1). This method is called on every turn,
	// and the player state is passed at the last parameter.
	AsGoalkeeper(ctx context.Context, inspector SnapshotInspector, state PlayerState) ([]proto.PlayerOrder, string, error)

	OnGetReady(ctx context.Context, inspector SnapshotInspector)
}

type Client 

type Client struct {
	Stream     proto.Game_JoinATeamClient
	GRPCClient proto.GameClient

	Logger Logger
	Sender OrderSender
	// contains filtered or unexported fields
}

Client handle the gRPC stuff and provide you an easy way to handle the game messages

func NewClient 

func NewClient(config Config, logger *zap.SugaredLogger) (*Client, error)

NewClient creates a Lugo4Go client that will hide common logic and let you focus on your bot.

func (*Client) HandleConn 

func (c *Client) HandleConn(_ context.Context, sts stats.ConnStats)

HandleConn implements the interface required by gRPC rawBotWrapper

func (*Client) HandleRPC 

func (c *Client) HandleRPC(context.Context, stats.RPCStats)

HandleRPC implements the interface required by gRPC rawBotWrapper

func (*Client) Play 

func (c *Client) Play(rawBot RawBot) error

Play starts the player communication with the server. The RawBot will receive the raw snapshot from the game server. The context passed to the rawBotWrapper will be canceled as soon a new turn starts.

func (*Client) PlayAsBot 

func (c *Client) PlayAsBot(bot Bot) error

PlayAsBot is a sugared Play mode that uses an RawBot from coach package. Coach RawBot creates basic player states to help the development of new bots.

func (*Client) Stop 

func (c *Client) Stop() error

Stop drops the communication with the gRPC server.

func (*Client) TagConn 

func (c *Client) TagConn(ctx context.Context, _ *stats.ConnTagInfo) context.Context

TagConn implements the interface required by gRPC rawBotWrapper

func (*Client) TagRPC 

func (c *Client) TagRPC(ctx context.Context, _ *stats.RPCTagInfo) context.Context

TagRPC implements the interface required by gRPC rawBotWrapper

type Config 

type Config struct {

	// Full url to the gRPC server
	GRPCAddress     string          `json:"grpc_address"`
	Insecure        bool            `json:"insecure"`
	Token           string          `json:"token"`
	TeamSide        proto.Team_Side `json:"-"`
	Number          int             `json:"-"`
	InitialPosition *proto.Point    `json:"-"`
	// contains filtered or unexported fields
}

Config is the set of values expected as a initial configuration of the player

func DefaultInitBundle 

func DefaultInitBundle() (Config, field.Mapper, *zap.SugaredLogger, error)

DefaultInitBundle created a basic configuration that may be used by the client to connect to the server. It also creates a logger that is compatible with the lugo4go.rawBot.

type Logger 

type Logger interface {
	Debug(args ...interface{})
	Debugf(template string, args ...interface{})
	Infof(template string, args ...interface{})
	Warnf(template string, args ...interface{})
	Errorf(template string, args ...interface{})
	Fatalf(template string, args ...interface{})
}

type OrderSender 

type OrderSender interface {
	Send(ctx context.Context, turn uint32, orders []proto.PlayerOrder, debugMsg string) (*proto.OrderResponse, error)
}

type PlayerState 

type PlayerState string

PlayerState defines states specific for players 

const (
	// Supporting identifies the player supporting the teammate
	Supporting PlayerState = "supporting"
	// HoldingTheBall identifies the player holding	the ball
	HoldingTheBall PlayerState = "holding"
	// Defending identifies the player defending against the opponent team
	Defending PlayerState = "defending"
	// DisputingTheBall identifies the player disputing the ball
	DisputingTheBall PlayerState = "disputing"
)

type RawBot 

type RawBot interface {

	// TurnHandler is called every turn with the new game state
	TurnHandler(ctx context.Context, inspector SnapshotInspector) ([]proto.PlayerOrder, string, error)
	GetReadyHandler(ctx context.Context, inspector SnapshotInspector)
}

RawBot is required by the Lugo4Go client to handle each turn snapshot

type SnapshotInspector 

type SnapshotInspector interface {
	GetSnapshot() *proto.GameSnapshot
	GetMe() *proto.Player

	GetBall() *proto.Ball
	GetBallHolder() (*proto.Player, bool)
	IsBallHolder(player *proto.Player) bool

	GetTeam(side proto.Team_Side) *proto.Team
	GetMyTeam() *proto.Team
	GetOpponentTeam() *proto.Team

	GetPlayer(side proto.Team_Side, number int) *proto.Player
	GetMyTeamPlayers() []*proto.Player
	GetOpponentPlayers() []*proto.Player

	GetMyTeamGoalkeeper() *proto.Player
	GetOpponentGoalkeeper() *proto.Player

	MakeOrderMove(target proto.Point, speed float64) (*proto.Order_Move, error)
	MakeOrderMoveMaxSpeed(target proto.Point) (*proto.Order_Move, error)
	MakeOrderMoveFromPoint(origin, target proto.Point, speed float64) (*proto.Order_Move, error)
	MakeOrderMoveFromVector(vector proto.Vector, speed float64) *proto.Order_Move
	MakeOrderMoveByDirection(direction field.Direction, speed float64) *proto.Order_Move
	MakeOrderMoveToStop() *proto.Order_Move

	MakeOrderJump(target proto.Point, speed float64) (*proto.Order_Jump, error)

	MakeOrderKick(target proto.Point, speed float64) (*proto.Order_Kick, error)

	MakeOrderKickMaxSpeed(target proto.Point) (*proto.Order_Kick, error)

	MakeOrderCatch() *proto.Order_Catch
}

func NewGameSnapshotInspector 

func NewGameSnapshotInspector(botSide proto.Team_Side, playerNumber int, gameSnapshot *proto.GameSnapshot) (SnapshotInspector, error)

type Starter 

type Starter struct {
	Config Config
	Logger *zap.SugaredLogger
}

func NewDefaultStarter 

func NewDefaultStarter() (*Starter, field.Mapper, error)

func (*Starter) Run 

func (s *Starter) Run(bot Bot) error

func (*Starter) RunJustTurnHandler 

func (s *Starter) RunJustTurnHandler(handler RawBot) error

Source Files

View all Source files

Directories

Path Synopsis
examples
bot-interface
bot-interface/bot
turn-handler
pkg
geo

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.