The cl-steamworks-generator Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The cl-steamworks-generator Reference Manual

This is the cl-steamworks-generator Reference Manual, version 1.0.0, generated automatically by Declt version 2.4 patchlevel 1 "Will Decker" on Mon Jul 29 15:13:27 2019 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

## About cl-steamworks
This is a wrapper library to allow you to interface with the Valve SteamWorks API.

## Setup
This library does //not// ship the SteamWorks and SteamClient binaries. You must get your own copy from "Valve"(https://partner.steamgames.com/). Once you have the SDK, load ``cl-steamworks-generator`` and run the ``setup`` function. It should handle everything automatically from there. Once the files have been generated, restart your Lisp and load ``cl-steamworks``.

### Client
Typically you'll be running a client instance when you ship your game. To get SteamWorks started up and ready, simply create an instance of ``steamworks-client``, passing your game's AppID as the ``:app-id`` initarg. If your game was not launched through steam, or steam isn't running and the app-id file isn't set up, it will signal an error and prompt you to restart through steam. For testing purposes, if you don't have a valid AppID yet, you can use ``480``, the AppID of their example game.

When you are about to shut the game down again, make sure to call ``(free (steamworks))`` in order to clean everything up properly.

This is all you need to do to sell your game on Steam. If you want to access any other functionality that the SteamWorks API offers, please read their API documentation and, where available, the documentation of this library. Specifically, you should see "Ā§Concepts"(link Concepts) below.

### Server
When you are running a server instance for your game, you should instead proceed as follows: create an instance of ``steamworks-server``. You must pass the following arguments: 

- ``:app-id`` As before, the AppID of your game.
- ``:ip-address`` The IP address to bind to, ``"0.0.0.0"`` to broadcast on all interfaces.
- ``:steam-port`` The local port used to talk to the Steam servers.
- ``:game-port`` The port to listen on for new client connections.
- ``:query-port`` The port to listen on for server browser queries and pings.
- ``:server-mode`` What level of authentication to require from players.
- ``:version-string`` A version string for your server, to identify outdated servers.
- ``:server-depot`` The depot id of your game.
- ``:directory`` The directory name of your game.

After that you should set any additional options on the server, and then call ``(logon (interface 'steamgameserver T))``, possibly with a ``:token`` argument to achieve a non-anonymous logon.

When you are about to shut the server down again, make sure to call ``(free (steamworks))`` in order to clean everything up properly.

## Q&A
### Why are some of the functions not wrapped?
The wrapper specifically does //not// include parts that have been marked as deprecated, superseded, or unused. If you find yourself in the unfortunate situation of having to access one of those functions anyway, you can always fall back to directly calling the C functions from the ``cl-steamworks-cffi`` package and retrieving relevant handles and IDs of the objects with ``handle``.

### This Wrapper is Broken!
Huh. Please "let me know"(https://github.com/shinmera/cl-steamworks/issues/new) what's broken. It's entirely possible that a wide set of things don't work quite right yet, as I don't have the time to thoroughly test everything.

### SteamWorks updated and the new stuff is missing!
Thanks for noticing! Please "submit a pull request"(https://github.com/shinmera/cl-steamworks/pulls) with the relevant fixes.

## Misc
### Acknowledgements
Thanks to Garry Newman's "blog entry"(https://garry.tv/2016/11/01/steamworks-sdk/) and the "Facepunch.Steamworks"(https://github.com/Facepunch/Facepunch.Steamworks) effort in general. It helped tremendously in figuring out some of the very obscure and annoying bits of the API.

### A Note to Game Developers
The steamworks API offers a //lot// of tools. However, I heavily recommend not building your game in a way that depends on them. This means using other, independent libraries where possible, and keeping the Steam functionality in a separate, optional system. The reason is that, if you write your game integrated tightly with the Steam API, then you won't be able to sell your game outside of steam, and if steam ever decides to shut down or remove your game, it will simply be lost to time. For the preservation of the medium and your own marketability, I thus heavily recommend investing the time into making your game extensible enough to keep the Steam parts an optional addition.

## Concepts
This library wraps the entirety of the SteamWorks API and tries to bridge the gap from Lisp to C++ as well as possible. For this reason it often diverges from the SteamWorks API. Most of the time however these divergences are simply convenience functions that automatically handle things like memory allocation, argument parsing, error checking, and aggregation. As such, typically you should be able to simply use the lisp functions exposed by this library and not worry any further.

However, there are a few things that this library cannot do for you, due to a lack of insight into how your application operates. These details are described in the following sections.

### Callbacks
The first thing to note is that you should call the function ``run-callbacks`` regularly. This function will trigger callbacks //synchronously// within the calling thread. If you do not call it often enough you might be interpreting events too late. However, it is also not recommended to call it too often, such as once a frame, as that could degrade performance.

The SteamWorks API defines a lot of callbacks over all of its interfaces. Unless specifically noted in the documentation of the respective interface, cl-steamworks will not handle the callback event at all. If there are events you care about, you should use ``define-callback`` to register a global callback function that can handle the event. If you want to track application context within a callback, you can use a dynamic variable and make sure to bind it when you call ``run-callbacks``, as the callback functions will be executed synchronously within the thread. Naturally you should also make sure not to call ``run-callbacks`` in time-critical code or implement time-consuming callback functions if you do.

### Callresults
In addition to callbacks, the SteamWorks API implements callresults. Callresults are handles for an asynchronous operation that you initiate. Most of the time when callresults are involved in the steam API, cl-steamworks will not expose them to you and instead implement a polling mechanism to wait for the result and then return synchronously. Sometimes the function will expose a ``:poll`` parameter to which you can pass ``NIL`` in order to retrieve the ``callresult`` instance instead of blocking. It is then up to you to retrieve the result at the opportune time.

### Memory and GC
Typically all objects that do require manual cleanup are wrapped as a ``c-managed-class``. This means that their resource will be automatically freed if the reference is lost and a GC cycle frees the Lisp object. However, you can, and are encouraged to, always free the objects manually with an explicit call to ``free`` whenever you know that it is safe to do so. In other words, the automatic GC should only be treated as a safety net, not an active feature to rely on. The reason for this is that the time at which the GC is completely unpredictable, so it is much harder to ensure the deallocation happens during an opportune time.

### Low Level
The direct SteamWorks API functions, constants, enums, and structures are exposed through the ``org.shirakumo.fraf.steamworks.cffi`` package. This package does //not// export anything explicitly. If you find yourself needing to deal with it, then you should add a package local nickname to your package definition like so: ``(:local-nicknames (#:steam #:org.shirakumo.fraf.steamworks.cffi))`` and access the symbols through ``steam::x``.

You can retrieve the underlying handles of objects with the ``handle`` function. For ``interface-object``s, you can use ``iface`` to retrieve its respective interface, and ``iface*`` to directly retrieve the handle of the interface.

Structures are exposed through a respective C struct type, but are also automatically translated to an equivalent Lisp structure when dereferenced from memory. Structures that are used as a callback or callresult are also associated with an ID that's necessary for the API. This mapping is done through the ``callback-type-id`` function. The inverse, of looking up a structure for a callresult function is done through the ``function-callresult`` function. Typically you should not have to touch this stuff however, as the ``callresult`` mechanisms in the wrapper take care of the details.

The callbacks in particular are handled through C structs that follow a very precise memory layout to emulate the C++ class instance that the SteamWorks API expects to see. You //really// should not have to deal with that yourself.

The rest of the meddling with the low level interface simply deals with standard CFFI stuff. Please consult the "CFFI manual"(https://common-lisp.net/project/cffi/manual/cffi-manual.html).

### Octet Buffers
Some API calls expect you to pass an octet vector to copy data into. If this is the case, the vector //must// be ready to be passed to C without copying. In effect this means that you must allocate the vector using ``cffi:make-shareable-byte-vector``. On some implementations, like SBCL, any simple-array octet vector is equivalent to one created using the above function. In general though, if portability is important, you must use ``cffi:make-shareable-byte-vector``.


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 cl-steamworks-generator

Maintainer

Nicolas Hafner <shinmera@tymoon.eu>

Author

Nicolas Hafner <shinmera@tymoon.eu>

Home Page

https://github.com/Shinmera/cl-steamworks

License

zlib

Description

Generator for the low-level steamworks bindings.

Version

1.0.0

Dependencies
Source

cl-steamworks-generator.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 cl-steamworks-generator.asd

Location

cl-steamworks-generator.asd

Systems

cl-steamworks-generator (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 cl-steamworks-generator/package.lisp

Parent

cl-steamworks-generator (system)

Location

package.lisp

Packages

cl-steamworks


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.3 cl-steamworks-generator/c-support.lisp

Dependency

package.lisp (file)

Parent

cl-steamworks-generator (system)

Location

c-support.lisp

Internal Definitions

Previous: , Up: Lisp files   [Contents][Index]

3.1.4 cl-steamworks-generator/generator.lisp

Dependency

c-support.lisp (file)

Parent

cl-steamworks-generator (system)

Location

generator.lisp

Packages

cl-steamworks-generator

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Next: , Previous: , Up: Packages   [Contents][Index]

4.1 cl-steamworks

Source

package.lisp (file)

Nickname

org.shirakumo.fraf.steamworks

Use List

common-lisp

Internal Definitions

Previous: , Up: Packages   [Contents][Index]

4.2 cl-steamworks-generator

Source

generator.lisp (file)

Nickname

org.shirakumo.fraf.steamworks.generator

Use List
Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Special variables

Special Variable: *extras-file*
Package

cl-steamworks-generator

Source

generator.lisp (file)

Special Variable: *standard-low-level-file*
Package

cl-steamworks-generator

Source

generator.lisp (file)


Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 Functions

Function: generate SOURCE &key OUTPUT IF-EXISTS
Package

cl-steamworks-generator

Source

generator.lisp (file)

Function: setup &optional SDK-DIRECTORY
Package

cl-steamworks-generator

Source

generator.lisp (file)


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Special variables

Special Variable: *bad-consts*
Package

cl-steamworks-generator

Source

generator.lisp (file)

Special Variable: *bad-structs*
Package

cl-steamworks-generator

Source

generator.lisp (file)

Special Variable: *bad-types*
Package

cl-steamworks-generator

Source

generator.lisp (file)

Special Variable: *c-type-map*
Package

cl-steamworks-generator

Source

generator.lisp (file)

Special Variable: *large-structs*
Package

cl-steamworks-generator

Source

generator.lisp (file)

Special Variable: *low-level-present*
Package

cl-steamworks

Source

c-support.lisp (file)

Special Variable: *static*
Package

cl-steamworks

Source

c-support.lisp (file)

Special Variable: *this*
Package

cl-steamworks

Source

c-support.lisp (file)

Special Variable: *this*
Package

cl-steamworks-generator

Source

generator.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Compiler macros

Compiler Macro: callback-type-id CALLBACK
Package

cl-steamworks

Source

c-support.lisp (file)

Compiler Macro: function-callresult FUNCTION
Package

cl-steamworks

Source

c-support.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.3 Functions

Function: %structure-types-p METHOD
Package

cl-steamworks-generator

Source

generator.lisp (file)

Function: c-slot-value-extractor STRUCT SLOTDEF
Package

cl-steamworks

Source

c-support.lisp (file)

Function: callback-type-id CALLBACK
Package

cl-steamworks

Source

c-support.lisp (file)

Function: compile-callback DEF
Package

cl-steamworks-generator

Source

generator.lisp (file)

Function: compile-callresult DEF
Package

cl-steamworks-generator

Source

generator.lisp (file)

Function: compile-const DEF
Package

cl-steamworks-generator

Source

generator.lisp (file)

Function: compile-enum DEF
Package

cl-steamworks-generator

Source

generator.lisp (file)

Function: compile-function DEF
Package

cl-steamworks-generator

Source

generator.lisp (file)

Function: compile-method DEF CACHE
Package

cl-steamworks-generator

Source

generator.lisp (file)

Function: compile-steam-api-spec SPEC
Package

cl-steamworks-generator

Source

generator.lisp (file)

Function: compile-struct DEF
Package

cl-steamworks-generator

Source

generator.lisp (file)

Function: compile-typedef DEF
Package

cl-steamworks-generator

Source

generator.lisp (file)

Function: copy-directory-contents SOURCE DEST
Package

cl-steamworks-generator

Source

generator.lisp (file)

Function: function-callresult FUNCTION
Package

cl-steamworks

Source

c-support.lisp (file)

Function: generate-shim SDK
Package

cl-steamworks-generator

Source

generator.lisp (file)

Function: kw NAME
Package

cl-steamworks-generator

Source

generator.lisp (file)

Function: maybe-compile-low-level &optional FILE
Package

cl-steamworks

Source

c-support.lisp (file)

Function: maybe-load-low-level &optional FILE
Package

cl-steamworks

Source

c-support.lisp (file)

Function: merge-steam-api-spec INTO &rest THINGS
Package

cl-steamworks-generator

Source

generator.lisp (file)

Function: name STRING
Package

cl-steamworks-generator

Source

generator.lisp (file)

Function: parse-typespec SPECSTRING
Package

cl-steamworks-generator

Source

generator.lisp (file)

Function: prefix-p PREFIX STRING
Package

cl-steamworks-generator

Source

generator.lisp (file)

Function: query-directory ()
Package

cl-steamworks-generator

Source

generator.lisp (file)

Function: read-steam-api-spec SOURCE
Package

cl-steamworks-generator

Source

generator.lisp (file)

Function: scan-all-headers DIRECTORY
Package

cl-steamworks-generator

Source

generator.lisp (file)

Function: scan-for-callbacks CONTENT
Package

cl-steamworks-generator

Source

generator.lisp (file)

Function: scan-for-constants CONTENT
Package

cl-steamworks-generator

Source

generator.lisp (file)

Function: split SPLIT STRING
Package

cl-steamworks-generator

Source

generator.lisp (file)

Function: strip-constant-name NAME
Package

cl-steamworks-generator

Source

generator.lisp (file)

Function: strip-function-name NAME
Package

cl-steamworks-generator

Source

generator.lisp (file)

Function: strip-hungarian STRING
Package

cl-steamworks-generator

Source

generator.lisp (file)

Function: strip-prefixes STRING &rest PREFIXES
Package

cl-steamworks-generator

Source

generator.lisp (file)

Function: strip-struct-name NAME
Package

cl-steamworks-generator

Source

generator.lisp (file)

Function: strip-suffixes STRING &rest SUFFIXES
Package

cl-steamworks-generator

Source

generator.lisp (file)

Function: suffix-p SUFFIX STRING
Package

cl-steamworks-generator

Source

generator.lisp (file)

Function: translate-name STRING
Package

cl-steamworks-generator

Source

generator.lisp (file)

Function: write-form FORM &optional STREAM
Package

cl-steamworks-generator

Source

generator.lisp (file)

Function: write-low-level-file FORMS &key OUTPUT IF-EXISTS
Package

cl-steamworks-generator

Source

generator.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   C   F   L  
Index Entry  Section

C
cl-steamworks-generator.asd: The cl-steamworks-generator<dot>asd file
cl-steamworks-generator/c-support.lisp: The cl-steamworks-generator/c-support<dot>lisp file
cl-steamworks-generator/generator.lisp: The cl-steamworks-generator/generator<dot>lisp file
cl-steamworks-generator/package.lisp: The cl-steamworks-generator/package<dot>lisp file

F
File, Lisp, cl-steamworks-generator.asd: The cl-steamworks-generator<dot>asd file
File, Lisp, cl-steamworks-generator/c-support.lisp: The cl-steamworks-generator/c-support<dot>lisp file
File, Lisp, cl-steamworks-generator/generator.lisp: The cl-steamworks-generator/generator<dot>lisp file
File, Lisp, cl-steamworks-generator/package.lisp: The cl-steamworks-generator/package<dot>lisp file

L
Lisp File, cl-steamworks-generator.asd: The cl-steamworks-generator<dot>asd file
Lisp File, cl-steamworks-generator/c-support.lisp: The cl-steamworks-generator/c-support<dot>lisp file
Lisp File, cl-steamworks-generator/generator.lisp: The cl-steamworks-generator/generator<dot>lisp file
Lisp File, cl-steamworks-generator/package.lisp: The cl-steamworks-generator/package<dot>lisp file

Jump to:   C   F   L  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   %  
C   F   G   K   M   N   P   Q   R   S   T   W  
Index Entry  Section

%
%structure-types-p: Internal functions

C
c-slot-value-extractor: Internal functions
callback-type-id: Internal compiler macros
callback-type-id: Internal functions
compile-callback: Internal functions
compile-callresult: Internal functions
compile-const: Internal functions
compile-enum: Internal functions
compile-function: Internal functions
compile-method: Internal functions
compile-steam-api-spec: Internal functions
compile-struct: Internal functions
compile-typedef: Internal functions
Compiler Macro, callback-type-id: Internal compiler macros
Compiler Macro, function-callresult: Internal compiler macros
copy-directory-contents: Internal functions

F
Function, %structure-types-p: Internal functions
Function, c-slot-value-extractor: Internal functions
Function, callback-type-id: Internal functions
Function, compile-callback: Internal functions
Function, compile-callresult: Internal functions
Function, compile-const: Internal functions
Function, compile-enum: Internal functions
Function, compile-function: Internal functions
Function, compile-method: Internal functions
Function, compile-steam-api-spec: Internal functions
Function, compile-struct: Internal functions
Function, compile-typedef: Internal functions
Function, copy-directory-contents: Internal functions
Function, function-callresult: Internal functions
Function, generate: Exported functions
Function, generate-shim: Internal functions
Function, kw: Internal functions
Function, maybe-compile-low-level: Internal functions
Function, maybe-load-low-level: Internal functions
Function, merge-steam-api-spec: Internal functions
Function, name: Internal functions
Function, parse-typespec: Internal functions
Function, prefix-p: Internal functions
Function, query-directory: Internal functions
Function, read-steam-api-spec: Internal functions
Function, scan-all-headers: Internal functions
Function, scan-for-callbacks: Internal functions
Function, scan-for-constants: Internal functions
Function, setup: Exported functions
Function, split: Internal functions
Function, strip-constant-name: Internal functions
Function, strip-function-name: Internal functions
Function, strip-hungarian: Internal functions
Function, strip-prefixes: Internal functions
Function, strip-struct-name: Internal functions
Function, strip-suffixes: Internal functions
Function, suffix-p: Internal functions
Function, translate-name: Internal functions
Function, write-form: Internal functions
Function, write-low-level-file: Internal functions
function-callresult: Internal compiler macros
function-callresult: Internal functions

G
generate: Exported functions
generate-shim: Internal functions

K
kw: Internal functions

M
maybe-compile-low-level: Internal functions
maybe-load-low-level: Internal functions
merge-steam-api-spec: Internal functions

N
name: Internal functions

P
parse-typespec: Internal functions
prefix-p: Internal functions

Q
query-directory: Internal functions

R
read-steam-api-spec: Internal functions

S
scan-all-headers: Internal functions
scan-for-callbacks: Internal functions
scan-for-constants: Internal functions
setup: Exported functions
split: Internal functions
strip-constant-name: Internal functions
strip-function-name: Internal functions
strip-hungarian: Internal functions
strip-prefixes: Internal functions
strip-struct-name: Internal functions
strip-suffixes: Internal functions
suffix-p: Internal functions

T
translate-name: Internal functions

W
write-form: Internal functions
write-low-level-file: Internal functions

Jump to:   %  
C   F   G   K   M   N   P   Q   R   S   T   W  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *  
S  
Index Entry  Section

*
*bad-consts*: Internal special variables
*bad-structs*: Internal special variables
*bad-types*: Internal special variables
*c-type-map*: Internal special variables
*extras-file*: Exported special variables
*large-structs*: Internal special variables
*low-level-present*: Internal special variables
*standard-low-level-file*: Exported special variables
*static*: Internal special variables
*this*: Internal special variables
*this*: Internal special variables

S
Special Variable, *bad-consts*: Internal special variables
Special Variable, *bad-structs*: Internal special variables
Special Variable, *bad-types*: Internal special variables
Special Variable, *c-type-map*: Internal special variables
Special Variable, *extras-file*: Exported special variables
Special Variable, *large-structs*: Internal special variables
Special Variable, *low-level-present*: Internal special variables
Special Variable, *standard-low-level-file*: Exported special variables
Special Variable, *static*: Internal special variables
Special Variable, *this*: Internal special variables
Special Variable, *this*: Internal special variables

Jump to:   *  
S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   C   P   S  
Index Entry  Section

C
cl-steamworks: The cl-steamworks package
cl-steamworks-generator: The cl-steamworks-generator system
cl-steamworks-generator: The cl-steamworks-generator package

P
Package, cl-steamworks: The cl-steamworks package
Package, cl-steamworks-generator: The cl-steamworks-generator package

S
System, cl-steamworks-generator: The cl-steamworks-generator system

Jump to:   C   P   S