README.txt
author Ryan C. Gordon <icculus@icculus.org>
Wed, 16 Sep 2015 01:21:44 -0400
changeset 12 d9821f628cc6
child 15 4018ba1b0e14
permissions -rw-r--r--
Added a README.
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
12
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
     1
What is this?
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
     2
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
     3
This is a small piece of code, written in C++, that acts as a bridge between
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
     4
a child process and the Steamworks SDK. The child process links against a
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
     5
small piece of code, written in C, to facilitate communication with the
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
     6
bridge.
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
     7
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
     8
What would I ever need this for?
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
     9
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    10
There are two good reasons to use this piece of code:
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    11
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    12
- You have a GPL-licensed game and can't link directly against the Steamworks
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    13
SDK. The child process links against the simple, open source C code, which
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    14
talks to the open source C++ code via a pipe, which talks to Steamworks. You
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    15
can now add Steam achievements to your game without violating the GPL.
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    16
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    17
- You have a game written in a programming language that can't interact with
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    18
C++ directly, so you can't make use of the Steamworks SDK directly. If your
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    19
language can link to C-callable code, you can use this to wire up to
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    20
Steamworks.
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    21
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    22
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    23
How does it work?
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    24
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    25
- The parent process (the C++ code) gets launched as if it were your game. It
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    26
initializes Steamworks, creates some pipes and launches your actual game, then
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    27
waits on your game to talk to it over those pipes.
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    28
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    29
- Your game links against steamshim_child.c and at some point #includes
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    30
steamshim_child.h to use this functionality.
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    31
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    32
- Your game calls STEAMSHIM_init() at startup to prepare the system. It can
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    33
then make other STEAMSHIM_*() calls to interact with the parent process and
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    34
Steamworks.
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    35
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    36
- Your game, once a frame, calls STEAMSHIM_pump() until it returns NULL. Each
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    37
time it doesn't return NULL is a new message (event) from the parent process.
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    38
Often times, this is results from a command you asked the parent process to
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    39
do earlier, or some other out-of-band event from Steamworks.
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    40
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    41
- Your game, when shutting down normally, calls STEAMSHIM_deinit(), so the
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    42
parent process knows you're going away. It says goodbye, shuts down the pipe,
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    43
waits for your game to terminate, and then terminates itself.
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    44
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    45
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    46
Is this all of Steamworks?
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    47
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    48
- No! It's actually just enough to deal with stats and achievements right now,
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    49
but it can definitely be extended to offer more things. Take a look at
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    50
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    51
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    52
Is there an example?
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    53
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    54
That would be testapp.c. This example expects you to own Postal 1 on Steam and
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    55
will RESET ALL YOUR ACHIEVEMENTS, so be careful running it. But hey, if you
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    56
lose your work, it's a good exercise in SteamShim usage to put them back
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    57
again.  :)
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    58
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    59
Questions? Ask me.
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    60
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    61
--ryan.
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    62
icculus@icculus.org
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    63
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    64