README.txt
author Ryan C. Gordon <icculus@icculus.org>
Wed, 16 Sep 2015 01:33:55 -0400
changeset 15 4018ba1b0e14
parent 12 d9821f628cc6
child 16 5b3ccd27fdd3
permissions -rw-r--r--
A couple README updates.
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
15
4018ba1b0e14 A couple README updates.
Ryan C. Gordon <icculus@icculus.org>
parents: 12
diff changeset
     3
- This is a small piece of code, written in C++, that acts as a bridge between
12
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
15
4018ba1b0e14 A couple README updates.
Ryan C. Gordon <icculus@icculus.org>
parents: 12
diff changeset
    25
- You get a copy of the Steamworks SDK, and link steamshim_parent.cpp against
4018ba1b0e14 A couple README updates.
Ryan C. Gordon <icculus@icculus.org>
parents: 12
diff changeset
    26
it. You ship that program and the steam_api.dll (or whatever) with your game.
4018ba1b0e14 A couple README updates.
Ryan C. Gordon <icculus@icculus.org>
parents: 12
diff changeset
    27
12
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    28
- 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
    29
initializes Steamworks, creates some pipes and launches your actual game, then
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    30
waits on your game to talk to it over those pipes.
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 links against steamshim_child.c and at some point #includes
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    33
steamshim_child.h to use this functionality.
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    34
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    35
- 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
    36
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
    37
Steamworks.
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    38
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    39
- 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
    40
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
    41
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
    42
do earlier, or some other out-of-band event from Steamworks.
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    43
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    44
- Your game, when shutting down normally, calls STEAMSHIM_deinit(), so the
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    45
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
    46
waits for your game to terminate, and then terminates itself.
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
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    49
Is this all of Steamworks?
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
- 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
    52
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
    53
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    54
15
4018ba1b0e14 A couple README updates.
Ryan C. Gordon <icculus@icculus.org>
parents: 12
diff changeset
    55
How do I get the Steamworks SDK?
4018ba1b0e14 A couple README updates.
Ryan C. Gordon <icculus@icculus.org>
parents: 12
diff changeset
    56
4018ba1b0e14 A couple README updates.
Ryan C. Gordon <icculus@icculus.org>
parents: 12
diff changeset
    57
- Go to https://partner.steamgames.com/ and login with your Steam account. You
4018ba1b0e14 A couple README updates.
Ryan C. Gordon <icculus@icculus.org>
parents: 12
diff changeset
    58
can agree to some terms and then download the SDK.
4018ba1b0e14 A couple README updates.
Ryan C. Gordon <icculus@icculus.org>
parents: 12
diff changeset
    59
4018ba1b0e14 A couple README updates.
Ryan C. Gordon <icculus@icculus.org>
parents: 12
diff changeset
    60
12
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    61
Is there an example?
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    62
15
4018ba1b0e14 A couple README updates.
Ryan C. Gordon <icculus@icculus.org>
parents: 12
diff changeset
    63
- That would be testapp.c. This example expects you to own Postal 1 on Steam and
12
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    64
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
    65
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
    66
again.  :)
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    67
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    68
Questions? Ask me.
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    69
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    70
--ryan.
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    71
icculus@icculus.org
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    72
d9821f628cc6 Added a README.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    73