Package: lugo4py
Lugo4Py - A Lugo Bots ClientLugo4Py is a Python implementation of a client player forLugogame.Itis not a botthat plays the game, it is only the client to connect to the game server.This package 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 projectexampefolder).Table of ContentsRequirementsInstallationUsageFirst option: Implementing a Bot class (simpler and recommended)Second option: Using reinforcement learning :brain:HelpersSnapshot readerMapper and Region classesThe MapperThe Regionrequirementspip~=23.1.2Installationpip install lugo4pyUsageLugo4Pyimplements 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.Implement theBot interfaceto handle each player state based on the ball possession.classBot(ABC):@abstractmethoddefon_disputing(self,orderSet:lugo4py.OrderSet,snapshot:lugo4py.GameSnapshot)->lugo4py.OrderSet:# on_disputing is called when no one has the ball possessionpass@abstractmethoddefon_defending(self,orderSet:lugo4py.OrderSet,snapshot:lugo4py.GameSnapshot)->lugo4py.OrderSet:# OnDefending is called when an opponent player has the ball possessionpass@abstractmethoddefon_holding(self,orderSet:lugo4py.OrderSet,snapshot:lugo4py.GameSnapshot)->lugo4py.OrderSet:# OnHolding is called when this bot has the ball possessionpass@abstractmethoddefon_supporting(self,orderSet:lugo4py.OrderSet,snapshot:lugo4py.GameSnapshot)->lugo4py.OrderSet:# OnSupporting is called when a teammate player has the ball possessionpass@abstractmethoddefas_goalkeeper(self,orderSet:lugo4py.OrderSet,snapshot:lugo4py.GameSnapshot,state:PLAYER_STATE)->lugo4py.OrderSet:# 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.pass@abstractmethoddefgetting_ready(self,snapshot:lugo4py.GameSnapshot):# getting_ready will be called before the game starts and after a goal event. You will only need to implement# this method in very rare cases.passFirst option: Implementing a Bot class (simpler and recommended)SeeexampleLugo4pyclient implements the methodplay_as_bot(bot)that expects an instancebotimplementation.All you need to do is creating your bot by extending that class and implementing your bot behaviour. See an example
atexample/simple/my_bot.pySecond option: Using reinforcement learning :brain:If you are amachine learningenthusiastic you may want to use the Lugo reinforcement learning environment.Lugo botsis an asynchronous game, so you will need to use theLugo4py Gymlibrary to create your model:See example and documentation atRL lib readme fileKick-startEe encourage you to cloneThe Dummies Pyproject and start from there. The read me file will have all
details you need.Deploying you botsAfter developing your bot, you may share it with other developers.Please find the instructions for uploading your bot onlugobots.dev.There is a Dockerfile template inthe example directoryto guide you how to create a container.HelpersThere 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.This package brings a collection of functions that will help you get that data from the game snapshot:config=lugo4py.EnvVarLoader()reader=lugo4py.GameSnapshotReader(snapshot,bot.side)Mapper and RegionThis package also provides a quite useful pair: the Mapper and Region classes.The MapperMapperslices 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 10x5map=lugo4py.Mapper(10,5,config.get_bot_team_side())targetRegion=map.get_region(5,2)my_region=mapper.get_region_from_point(me.position)The RegionTheMapperwill slice the field intoRegions. The Region struct helps your bot to move over the field without caring
about coordinates or team side.target_region=map.get_region_from_point(bot.position)region_in_front_of_me=target_region.front()region_in_back_of_me=target_region.back()region_in_left_of_me=target_region.left()region_in_right_of_me=target_region.right()my_col=target_region.get_col()my_row=target_region.get_row()moveOrder,err_:=reader.makeOrderMoveMaxSpeed(position,region_in_front_of_me.center)Snapshot readerThe Snapshot reader is quite useful. Firs to it helps you to extract data from
theGame Snapshoteach game turn.reader=lugo4py.GameSnapshotReader(snapshot,self.side)reader.get_my_team()reader.get_team(side)reader.is_ball_holder(player)reader.get_opponent_side()reader.get_my_goal()reader.get_opponent_goal()reader.get_player(side,number)And also help us to create
theTurn Orders Setbased on the game state
and our bot team side:reader=lugo4py.GameSnapshotReader(snapshot,bot.side)reader.make_order_jump(origin,target,speed)reader.make_order_kick(ball,target,speed)reader.make_order_kick_max_speed(ball,target)reader.make_order_move(origin,target,speed)reader.make_order_move_from_vector(direction,speed)reader.make_order_move_max_speed(origin,target)reader.make_order_catch()And, last but not least, the Reader also helps our bot to see the game map based on directions instead of coordinates:reader.make_order_move_by_direction(DIRECTION.FORWARD)reader.make_order_move_by_direction(DIRECTION.BACKWARD)reader.make_order_move_by_direction(DIRECTION.LEFT)reader.make_order_move_by_direction(DIRECTION.RIGHT)reader.make_order_move_by_direction(DIRECTION.BACKWARD_LEFT)reader.make_order_move_by_direction(DIRECTION.BACKWARD_RIGHT)reader.make_order_move_by_direction(DIRECTION.FORWARD_LEFT)reader.make_order_move_by_direction(DIRECTION.FORWARD_RIGHT)The trainable botThe trainable bot is an interface definedheredocker run -p 8080:8080 -p 5000:5000 lugobots/server:latest play --dev-mode --timer-mode=remote

python3 -m example.rl.main