j4nk
/
open-card-table
1
0
Fork 0
Code Issues 7 Pull Requests Projects Releases Wiki Activity

Update 'README.md'

This commit is contained in:
j4nk 2023-08-08 23:02:53 -04:00
parent d5e7891af1
commit 98f8e3d962
1 changed files with 12 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
README.md
View File

@ -2,7 +2,8 @@
## A text-based tabletop game engine written in C and scripted with Lua
### Motivation
I originally came up with this idea for the purpose of understanding the interaction between a rendering engine, game logic, and a scripting language along with learning how to use the C-Lua interface, learning the Unix sockets API, and experiencing firsthand manual memory management on a decently-sized project. Additionally, this project fills a gap I perceive in the open source gaming community; that is, a way to play tabletop games with friends on basically any *NIX system with a CPU. Indeed, this project runs only in the terminal; as of yet there are no graphical capabilities. It should be noted that the project has only been compiled on Linux, once the game is complete I will add in the necessary code for building on MacOS, OpenBSD, and FreeBSD. Earlier, when I ran OpenBSD on my laptop the game was maintaining compatibility with OpenBSD but I have since quit using that computer and OpenBSD compatibility has not been tested in a long time - it will almost certainly not build on OpenBSD.
I originally came up with this idea for the purpose of understanding the interaction between a rendering engine, game logic, and a scripting language along with learning how to use the C-Lua interface, learning the Unix sockets API, and experiencing firsthand manual memory management on a decently-sized project. Additionally, this project fills a gap I perceive in the open source gaming community; that is, a way to play tabletop games with friends on basically any *NIX system with a CPU. Indeed, this project runs only in the terminal; as of yet there are no graphical capabilities. It should be noted that the project has only been compiled on Linux, once the game is complete I will add in the necessary code for building on MacOS, OpenBSD, and FreeBSD.
### Targets
Currently, the only target is Linux. After the game is finished, it will target Mac OSX, OpenBSD, and FreeBSD. Other targets may be added after that. Windows support is not planned, however it *may* be possible to run this in WSL, I have no idea how well WSL works with the Unix sockets API.
@ -10,11 +11,16 @@ Currently, the only target is Linux. After the game is finished, it will target
Currently, the only dependencies are [termbox2](https://github.com/termbox/termbox2) and Lua 5.3. An older version of termbox2 is included in the repository for convenience. I used termbox2 instead of ncurses because ncurses leaks memory, and one of my goals for this project is to not leak memory at all. Also, termbox2 is much, much simpler than ncurses in my opinion. I plan on upgrading to Lua 5.4 eventually, when I began this project Lua 5.4 was already out but a tutorial I was following was using Lua 5.3.
### License
I have not chosen a license for this project yet. Will definitely have one by the time version 1.0 comes out.
This project is released under the MIT license. This means that you can basically do anything you want with it, including forking the code and releasing that under a nonfree license.
### Building
`cd` to the directory and do `make`. This will almost certainly not work on a non-Linux system right now.
### Usage
`open_card_table \[options\] LUA_FILE`
`open_card_table [options] LUA_FILE`
LUA_FILE is the file to run
Options may be
- `-p PORT`: Port to listen on for connections
- `-v`: Prints version
@ -71,7 +77,8 @@ end
**Note that at this time, networking is incomplete and only basic functionality is working.** Networking consists of the `oct_recv` and `oct_send` functions. Note that in order to use networking, `oct_init()` had to return `OCT_NEEDS_NETWORKING` as the first argument, or else nothing will happen. These usually are used in the `oct_loop` function. I still need to add in support for broadcasting, this will come in a while. **Important**: Message sending is *synchronous*, i.e. under the hood a message and destination are placed in buffers, and at the next invocation of the main loop the message is sent to the destination. I believe that tabletop games are simple enough that this is sufficient to express games even with real-time components as the main loop is executed at a high frequency. If this turns out not to be the case, I will look into adding asynchronous message sending.
##### Networking examples
Receiving a message: `msg,addr,port = oct_recv();`
Sending a message: `oct_send("MESSAGE", "IP_ADDRESS", "PORT")`;
Sending a message: `oct_send("MESSAGE", "IP_ADDRESS", "PORT");`
#### Logging
I have written a convenient logging interface for Lua, it uses the logging macros I implemented in C. It can be invoked in Lua via the `OCT_LOG_ERROR`, `OCT_LOG_INFO`, `OCT_LOG_WARNING`, and `OCT_LOG_DEBUG` functions, passing the desired string as an argument. Remember that termbox2 takes over the console, so it is a good idea to use the `-lf` switch to specify an output file if you are running a termbox-enabled program. Also remember that the log level needs to be set to a sufficient strength via `-ll` in order to see the messages.
I have written a convenient logging interface for Lua, it uses the logging macros I implemented in C. It can be invoked in Lua via the `OCT_LOG_ERROR`, `OCT_LOG_INFO`, `OCT_LOG_WARNING`, and `OCT_LOG_DEBUG` functions, passing the desired string as an argument. Remember that termbox2 takes over the console so it is a good idea to use the `-lf` switch to specify an output file if you are running a termbox-enabled program. Also remember that the log level needs to be set to a sufficient strength via `-ll` in order to see the messages.