LuaCatan

• Index

Contents

• Documentation
• Description
• Architecture
• Target audience
• Expected usage
• Key features
• Functional requirements
• Non-functional requirements
• Successful use cases
• Problematic use cases

Topics

• README
• TUTORIAL
• ABOUT

Modules

• catan.gui
• catan.logic.constants
• catan.logic.grid
• util.class
• util.logic
• util.platform
• util.safe
• util.schema
• util.table
• main

Classes

• catan.gui.Box
• catan.gui.Layer
• catan.gui.Sprite
• catan.logic.EdgeMap
• catan.logic.FaceMap
• catan.logic.Game
• catan.logic.HexProduction
• catan.logic.VertexMap

About this project

Description

LuaCatan is an implementation of the Settlers of Catan board game in Lua. It follows the base rules established by the 5th edition of the game, which are available here. The graphical user interface is implemented using LÖVE, and serialization/deserialization is performed by the Serpent library. LuaCatan has been tested extensively, reaching 100% of line coverage, as reported by LuaCov. Coverate reports in HTML can also be generated thanks to the LuaCov-HTML library. All modules have their own unit tests, and the main class catan.logic.Game has a special test bench, which tries random actions and checks if the state invariants are valid. This fuzzy tester can be configured through command line arguments, thanks to the argparse library. Apart from tests, all modules and classes are exhaustively documented. All this documentation is nicely converted into HTML by LDoc.

Architecture

LuaCatan is composed of two logical parts: the back-end and the front-end. This separation will be crucial for the implementation of the client and the server components. However, it is important to point out that both parts currently run on the same machine. The back-end part is written in Lua (5.1 or later), and uses the serpent library for serialization. Meanwhile, the front-end part is loaded by LÖVE (which still runs on Lua 5.1). Do note, however, that a central design goal of LuaCatan is to keep the front-end as uncoupled from the back-end as possible. This means that you should have no problem in programming your own front-end on top of the LuaCatan back-end.

Target audience

LuaCatan can be played by anyone that is already familiar with the rules of the game, but may require a level of technical knowledge above the average to set it up. We want to make LuaCatan as user-friendly and cross-platform as possible, specially for the client side. However, for the time being, the user must know how to download LÖVE and serpent to enjoy all the features of LuaCatan. Note that not all dependencies listed in the README.md are necessary for the execution of the client. Most dependencies are only required for the developer to build the documentation, or to run the tests.

Expected usage

We must acknowledge that there are several other implementations of Catan out there, such as colonist.io. They provide several interesting functionalities such as lobbies, custom maps, game settings, and a built-in chat. These implementations, however, require an internet connection, which might not always be available. For this reason, LuaCatan serves as an alternative to playing Catan offline. In the future, we would also like to implement an option to set up a LAN session, which would highly improve the user experience and interface.

Key features

Despite the long list of pending features, LuaCatan has several interesting feature already. For instance, you can save and load game states into/from Lua files, and run the client in debug mode, which allows you to draw as many resource cards as you like.

Functional requirements

The user must be able to start a match...

• with a random terrain
• with a random drawpile
• with 3 or 4 players (PENDING, can only play with 4 players)
• giving names to players (PENDING, players are identified by their color)

Players must have read access to...

• terrain hexes
• number tokens
• harbors
• the robber
• player roads
• player settlements
• player cities
• the amount of resource cards of each player
• the amount of development cards of each player
• the owner of the longest road special card
• the owner of the largest army special card
• their own resource cards
• their own development cards
• the amount of development cards in the drawpile (PENDING)
• the amount of each resource card in the bank (PENDING)

Players must not have access to...

• the resource cards of other players (PENDING, all resource cards are public)
• the development cards of other players (PENDING, all development cards are public)

On their turn, when the conditions described by the game rules are met, a player must be able to...

• build settlements
• build cities
• build roads
• roll the dice
• propose, commit and cancel trades to the other players
• trade through the harbors
• buy development cards
• play a development card
• end their turn

Not on their turn, a player must be able to...

• accept trade proposals (if possible)
• reject trade proposals

In the case of rolling a 7...

• all players must be able to discard half of their cards
• the player who rolled a 7 must be able to move the robber
• the player who rolled a 7 must be able to choose a victim

At any time, the user must also be able to...

• exit the game
• pause the game
• save the game
• load the game

Non-functional requirements

• the source code must be licensed with GPLv3
• the source code must only depend on free and open-source software
• any extra resources (such as images) must also be used under a free license
• the back-end and the front-end must be written in Lua >= 5.1
• the back-end must be as uncoupled from the front-end as possible
• the back-end should provide an entry point to validate the state of the game against a set of invariants
• the back-end must be easily run on Linux environments
• the front-end must use LÖVE >= 11.4
• the front-end may only listen to mouse and keyboard events
• the front-end must be easily run on any platform (PENDING, client-server separation)
• each Lua module must be thoroughly documented and tested
• the code documentation must be accessible in HTML format
• the ratio of program lines covered the tests must be >= 95%

Documentation

The front-end is documented in the TUTORIAL.md.

The back-end is fully documented by the pages generated by LDoc.

Successful use cases

Using the LuaCatan back-end

• Who is the user? The user has some level of expertise with Lua, and knows how to install the dependencies with LuaRocks. They are running Linux.
• In what context would LuaCatan be useful to the user? The user might want to use only the back-end, because they want to develop a front-end for it, for a university assignment.
• How would the user use LuaCatan? The user might fork the repository, and add their code next to the already existing code. They might iteratively improve the front-end to contemplate all possible game actions, and meta-actions such as serialization. They might resort to the reference front-end implementation in LÖVE to understand how the back-end should be used.
• What does the user expect from LuaCatan, and what would they do with the result of its usage? The user expects the back-end to properly implement the game rules; to have an easy-to-use interface; to raise erros whenever internal invariants are violated; to have sensible default values; to implement efficient algorithms in terms of computational effort and memory usage; and to have a thorough and clear documentation. With all of these properties, the user would be able to concentrate more on the development of the front-end instead of facing problems with the back-end. For the user of their front-end, they would benefit from having a reliable back-end, with efficient algorithms, etc.

Using the LuaCatan front-end

• Who is the user? The user has the dependencies installed on their machine, or knows how to install them. They are generally only interested in playing the game, and not on the implementation necessarily. They are running Linux.
• In what context would LuaCatan be useful to the user? The user would like to play Catan offline, given that most Catan implementations are Web-based and require an internet connection.
• How would the user use LuaCatan? They would install the dependencies and run the game through the command line, and then interact with LuaCatan through the GUI.
• What does the user expect from LuaCatan, and do with the result of its usage? They expect LuaCatan to faithfully reflect the analog board game, or other digital replicas. They also expect the GUI to be reliable, responsive, aesthetically pleasing, and intuitive. The user would also indirectly use the back-end, so it is crucial that the back-end also correctly and efficiently implements the game rules. Having played LuaCatan, the user would be satisfied with the game experience.

Problematic use cases

Using the LuaCatan back-end without external Lua dependencies

• Who is the user? The same as in the "Using the LuaCatan back-end" use case, except that they want the back-end to self-contained (no external packages needed).
• In what context would LuaCatan be useful to the user? The user might want to use only the back-end, because they want to develop a front-end for it, for a university assignment. They want the back-end to be as portable as possible, requiring the fewest number of installation steps as possible.
• How would the user use LuaCatan until they find the problem? They might visit the repository page on GitHub, and see that the back-end depends on Serpent for serialization.
• How would the user try to fix the problem? The user could try to fork the repository and make Serpent be an optional dependency for the back-end (which would still be necessary for serialization), or even implement a serialization/deserialization routine to be used internally.

Using the LuaCatan front-end in a competitive setting

• Who is the user? The user has the dependencies installed on their machine, or knows how to install them. They are interested in playing the game competitively with other players. They are running Linux.
• In what context would LuaCatan be useful to the user? The user would like to play Catan offline, given that most Catan implementations are Web-based and require an internet connection. Also, in a competitive setting, playing off-line would increase the security of the system as a whole (given that it would not be succeptible to remote attacks).
• How would the user use LuaCatan until they find the problem? The user would follow the installation steps properly, but when they test LuaCatan, they notice that it would not be fit for competitive settings, since all players play on the same machine, and all cards
• How would the user try to fix the problem? The user might establish that only one player may see the screen at any given moment, and that a mediator may coordinate who can see the screen. This does not solve the problem fully, as the number of victory points would still be displayed. If the user could hide this number, but this would hinder the user experience (as the players would need to calculate this number from the top of their heads).