PunkBuster Screenshots

Server:

• PB_SV_AutoSs
• PB_SV_AutoSsFrom
• PB_SV_AutoSsTo
• PB_SV_GetSs
• PB_SV_SsCeiling
• PB_SV_SsCmd
• PB_SV_SsDelay
• PB_SV_SsFloor
• PB_SV_SsHeight
• PB_SV_SsList
• PB_SV_SsLogging
• PB_SV_SsNext

Server (cont.):

• PB_SV_SsPath
• PB_SV_SsTimeout
• PB_SV_SsWidth
• PB_SV_SsSRate
• PB_SV_SsXPct
• PB_SV_SsYPct

Client:

• PB_GetSs
• PB_SsOptions
• PB_PList

PB Screenshot Concepts

PunkBuster Screenshots are taken in the background while the player is busy gaming. Since this is a background task, it cannot negatively affect the performance of the player by either taking up too much CPU usage, writing lots of data to the player's hard drive, or using up a lot of their internet connection's bandwidth. Therefore, the ideal solution of taking a full-screen high-definition screenshot of the player's view and uploading the resulting files to the server at regular intervals is not practical (unless the person has a really small screen and a fast computer, which is an uncommon combination).

There are restrictions put in place by PunkBuster in order to strike a balance between the desire to have as many useful and informative screenshots as possible and the need to prevent any negative performance consequences for the player:

• The total number of pixels in the screenshot may not exceed 82,000, and if a screenshot is requested where the number of pixels that would be returned is greater than that, the size of the screenshot will be automatically reduced to fit.
• No more than three screenshots can be requested from a player in a ten-minute period, and requests for any more than that will be ignored.
• PunkBuster will not attempt to take any screenshots if the game application is not active (it is minimized or does not have focus). This is primarily for privacy reasons.

The first restriction most significantly limits the options you have in taking screenshots as this restricts the area of the screen that can be captured in a single screenshot.

The Box: The Area of the Screen to be Captured

Given the restriction on the total number of pixels that can be returned, you can deduce that the limitation has the following practical effect (all terms are in pixels):

The width of the captured area of the screen is determined by the PB_SV_SsWidth setting and the height is likewise set by the PB_SV_SsHeight setting. By default, these values are 320 and 240 respectively, resulting in a total number of pixels captured of 76,800.

These measurements create a screenshot in the 4:3 aspect ratio, which is normal for standard-sized monitors (as opposed to wide-screen monitors). When creating a box in the 4:3 aspect ratio, the settings for height and width must fit into the following formulas:

and

It is not required to use a box that conforms to the 4:3 aspect ratio, however this is common practice. You can use any measurements you want to create a box of whatever size you want, so long as the total number of pixels does not exceed 82,000.

Sample Rate

It doesn't take too long to realize that being limited to only 82,000 pixels severely limits your ability to capture large areas of a player's screen. A player who has an 800x600 screen resolution is using 480,000 pixels, which is over five times greater than the limit. A player that has a 1024x768 resolution is using 786,432 pixels, which is more than nine times the limit. How is one supposed to capture a meaningfully-large area of player screens like this?

The answer is by taking advantage of the option to change the sample rate, which is defined using the PB_SV_SsSRate setting. The default sample rate is 1. What this means is that all of the pixels in the area to be captured (the box) will be captured. There are two other options for this setting, 2 and 4. If the the sample rate is set to two, every second row and column of pixels will be skipped, which has the effect of cutting the number of pixels captured to a fourth of the original amount. When the sample rate is set to four, three rows and columns of pixels are skipped, which has the effect of cutting the number of captured pixels to a sixteenth of the original amount.

To help you visualize this, look at the examples below. Each box on the checkerboard pattern represents one pixel (you're looking at a zoomed-in perspective of the capture area).

Sample Rate = 1	Sample Rate = 2	Sample Rate = 4
(All of the pixels are captured.)	(1/4 of the pixels are captured.)	(1/16 of the pixels are captured.)

By choosing to exclude certain pixels, you can increase the size of the box, however this comes at the cost of the loss of sharpness and clarity in the image. For the screenshot review process here at PunksBusted, a sample rate of four is considered to be too blurry to be used, so the options you have are either one or two.

Therefore, the formula for determining the size of the box you can use is:

which is the same as:

Assuming a sample rate of 2, the original 320x240 box can be doubled in size to 640x480 and still return the same number of pixels, 76,800. Remember that if you exceed the 82,000 pixel limit, the system will automatically resize your box to the nearest fit (given the proportion of the original width and height).

Placement of The Box on the Player's Screen

Now that you have figured out the size of the box and the sample rate you want to use, now you must decide what area of the screen will be captured. This is accomplished by positioning the box on a location on the player's screen. To accomplish this, there are two settings: PB_SV_SsXPct, which determines where the center point of the box will be placed on the horizontal axis (in percent), and PB_SV_SsYPct, which determines where the center point of the box will be placed on the vertical axis (in percent). The default value for both of these settings is 50, meaning that the center of the box will be halfway across both horizontal and vertical axes, making the box centered on the player's screen.

The top-left corner of the player's screen is the zero point on both the horizontal (X) and vertical (Y) axes. As you can see from the picture, when you move to the right, the X value increases, and when you move down, the Y value increases. These two values put together determine the center point of the box (which is shown as a blue dot in the above picture). It is important to remember that these values are percentages and NOT pixels. This ensures that the relative area of the screen to be captured will be placed in the same area of the screen, regardless of the screen resolution the player is using.

The box (the red rectangle) will always stay fully within the boundaries of the player's screen (the black rectangle), even if the center point is placed in an area where normally you would expect part of the box to go off the end of the screen. For example, using values of 100 for both settings places the box at the bottom-right corner of the player's screen. Even though the expected center point would be at the exact bottom-right pixel of the screen, this would cause most of the box to fall off the screen. The effect is that the bottom-right corner of the box will match up with the bottom-right corner of the screen, and the true center point will end up being somewhere further away from the defined position.

There is also a special value for these settings: -1. When set to -1, a random position on the axis will be chosen each time a screenshot is taken. You can use the -1 value on one or both of the axes to achieve the randomization of the box placement that you may desire.

Screenshot Delay

There are a few other considerations for how the screenshot facility will behave. One of these is the concept of screenshot delay.

If the PB_SV_SsDelay setting is set to a value greater than zero, but not greater than 60, a delay will be introduced between the time that the server makes a request to the client to take a screenshot and when it is actually taken. The default value is 0 (disabled). When it is not zero, a random value between zero and the given value of this setting will determine how many seconds the client will wait before taking the screenshot.

Screenshot Return Timeout

Another issue to consider is the amount of time that a client will have once they have been sent the screenshot request to actually return the screenshot to the server. This time limit is the return timeout setting, which is defined using the PB_SV_SsTimeout setting. This is the number of seconds that the client will have before the server gives up on the screenshot request. In general, each game will have its own default value for this setting and you may just want to leave it as it is, however you can adjust this setting if you have a high number of players who experience timeouts when sending back screenshots.

Remember that the primary activity going on for the client is them actually playing the game. Most of their internet traffic is devoted to this. Setting a timeout value that is too low will not allow clients to return a screenshot with enough time left over to prevent noticeable latency for the client.

Screenshot Logging

When a PunkBuster Screenshot is taken, verification information in the form of the date and time that the screenshot was taken plus a file sum of the completed screenshot file are noted by the server when the screenshot file is returned. This information is necessary to conclusively determine the validity of the screenshots to ensure that they are genuine. You have the option of logging this information to your PunkBuster server text log as well by using the PB_SV_SsLogging setting. A value of 0, which is the default, means that no screenshot data will be logged (but the screenshots themselves will still be taken). This is not recommended. Instead, you should choose one of the following options:

• 1 - Screenshot verification data will be added to the regular PB server log file.
• 2 - A separate log file for each screenshot will be created in the PB server log directory with the name [SerialNumber].ss where [SerialNumber] is the serial number that matches the one used for the screenshot file itself.
• 3 - Both of the actions in options 1 and 2 will be performed.

Generally, we recommend either using a value of 1 or 3 for this setting.

Handling the Returned Screenshots

When the screenshots from all the players on your server are eventually returned, they need to be stored somewhere so you can examine them later. There are a number of settings which can be used to customize how the returned screenshots are stored.

• PB_SV_SsPath - By default, the returned screenshots are stored in the svss subdirectory of the server's pb directory (which will be created automatically if it does not exist). The files stored here include the screenshot PNG images themselves as well as the helper .htm files that go with them (one that corresponds with each screenshot, and the pbsvss.htm file which shows all the available screenshots). The default value for this setting is "". Setting this to a path to another directory (even another network share) will change the location where the returned screenshots and their helper files are saved. Most game server administrators will not need to change this setting.
• PB_SV_SsFloor and PB_SV_SsCeiling - These settings determine the serial numbers used in the file names of the returned screenshots when they are stored on your server. The file names of the screenshots will be in the following format: pb[SSSSSS].png where [SSSSSS] is the serial number of the screenshot. The Floor setting determines the lowest-possible serial number (the default is 1) and the Ceiling setting determines the highest-possible serial number (the default is 100). By default, the first returned screenshot will have the file name: pb000001.png and the number is incremented with every screenshot until it reaches the Ceiling value. Once it hits this point, it starts again at the Floor value, overwriting any existing screenshots with the same serial number. The total number of screenshots your server will store is the value of the Ceiling setting minus the value of the Floor setting. Increasing the Ceiling setting while keeping the Floor setting constant will increase the total number of screenshots stored on your server. Keep in mind any hard drive space restrictions you may have to deal with on your server when choosing values for these settings.
• PB_SV_SsNext - This setting holds the serial number that will be used for the next screenshot. This value is updated automatically by PunkBuster, however you can set it manually if you desire, so long as the value for this setting is in between the values of the Floor and Ceiling values, inclusive.
• PB_SV_SsCmd - For those of you who want to be really fancy, you can have a script that you write handle returned screenshots. When this setting is set to a local path, PunkBuster will call that script automatically after a screenshot is successfully taken, passing the full path of the returned screenshot file as a parameter to the script. This could be used, for example, to automate the processing or publication of screenshots in a custom manner you desire. The uses for this setting are beyond the scope of this document. The default setting is "" which means that no action will be taken.

Capturing Screenshots

After what seems like a lot of work to get everything set up, you are now ready to start taking PunkBuster Screenshots. There are two methods for doing this on your server (manually and automatically) which can be used together if you desire.

Manual Capture

To manually capture player screenshots, the PB_SV_GetSs command is used. How this command behaves will depend on the edition of the Screen Capture Facility that is used in your game.

The basic command is as follows:

PB_SV_GetSs [Value]

[Value] can be one of the following:

• (blank) - A screenshot request will be sent to all players. This option is only available in the original version of this command.
• (number) - A specific player can be selected for a screenshot by providing their player slot number, which can be found using the PB_PList client command.
• "(name or search term)" - When a term that is not numeric or blank is provided, it will do a player name search for the term provided. In the original version of this command, screenshots will be requested from all players where the search term is present in their player names. In the updated version of this command, a screenshot request will only be sent to the first player name match. When searching in this manner, the term must be enclosed with double-quotes.

Here are some examples of the use of this command in its basic form:

PB_SV_GetSs

• All players will be sent screenshot requests. This option works only in the original version of this command.

PB_SV_GetSs 12

• The player who has the player slot number 12 will be sent a screenshot request.

PB_SV_GetSs "rock"

• In the original version of this command, any player who has the word "rock" in their player name will be sent a screenshot request. This would include players with the names: "rock" "Rocky" "rOcKmAn" "strong-as-a-rock" and so on. In the updated version, only the first player whose name matches the term will be sent the request.

When the Screen Capture Facility was updated in certain PB-supported games, the behavior of screenshot capturing on the client was changed. Previously, the client would only take screenshots when it was requested by the server and then immediately return them. In the revised Screen Capture Facility, the client takes its own screenshots in regular intervals and stores them in a queue, each with a unique sequence number. When the server makes a screenshot request, the client returns the most recent completed screenshot in the queue.

A limitation was placed on the PB_SV_GetSs command when this revision was made to the Screen Capture Facility which prevents the command from requesting screenshots from more than one client simultaneously. Therefore, the option for not providing a term no longer has the same effect as in the original version, and the option for searching for players by name is now limited to only the first result. The second option (providing a player slot number) has not changed.

The updated version of the command is as follows:

PB_SV_GetSs [Value] {[Sequence#]}

Besides the changes in behavior noted above, the other major change is the addition of an optional second parameter which accepts a valid screenshot sequence number for the indicated client. This sequence number is determined by running the PB_SV_SsList command for the player you want to specify.

The only way to determine which version of the command you can use is to attempt to run the PB_SV_SsList command. If it fails with an error saying that the command is unrecognized, then your game is still using the original edition of the Screen Capture Facility and the first command is used. Otherwise your game is using the updated Screen Capture Facility and the second command is used. Do not assume that a newer game will have the updated facility; only testing can confirm the actual edition in use.

Remember that you cannot issue more than three screenshot requests for any player in a ten-minute period, irrespective of what version of the Screen Capture Facility you have to work with.

Automatic Capture

Most game server administrators will not want to be constantly typing in one of the above manual commands in order to have regular screenshots taken, so there is also a process for automatically taking screenshots. This involves three settings:

• PB_SV_AutoSs - When set to 1, automatic screenshots will be taken in a manner determined by the following two settings. The default is 0 (disabled).
• PB_SV_AutoSsFrom and PB_SV_AutoSsTo - These values (in seconds) determine the lower and upper boundaries of a range, from within which PunkBuster will randomly choose a value each time a screenshot is taken. This chosen value is the number of seconds that PunkBuster will wait before sending the next automatic screenshot request. The default values for these settings are 60 and 1200 respectively, meaning that PunkBuster will wait anywhere from one to twenty minutes after the previous automatic screenshot request before issuing the next request.

As has been mentioned previously, the total number of screenshot requests for any given player (whether they are manual or automatic) cannot exceed three in a ten-minute period. Any additional request will be ignored.

You can see how many screenshot requests a player has received in the last ten minutes by using the PB_PList client command. In the results of this command, there is a column called Recent SS. This tells you the number of screenshot requests that the player has received in the last ten minutes.

Returned Screenshots

Now that you have captured some PunkBuster screenshots, it's time to explore what these screenshots are exactly and the information they provide. Below you will see an example of a returned screenshot.

In the top section of the screenshot, you can see the player's view. This screenshot is from America's Army and you can see part of the virtual compass and mini-map on the bottom-left corner of the screenshot area. The boundaries of this view are the area of the box you defined previously. It is placed on a black background as part of a larger image. The bottom section of the screenshot contains data about the screenshot and the player. The following guide will explain the content of the bottom section of the screenshot:

1:  PunkBuster Screenshot ([Status]) [Game] [Map]
2:  [SerialNumber] [ServerIP] [ServerName]
3:  *[GUID]* [PlayerName]
4:  Attempted: w=[AW] X h=[AH] at (x=[XPct]%,y=[YPct])
5:  Resulting: w=[RW] X h=[RH] sample=[SR] [UNK]

• Line 1
  • [Status] - Gives a representation of the result code for the screenshot operation. Possible values include:
    • B0 - Screenshot operation failed (error will be printed on line 5).
    • B1 - Screenshot operation succeeded.
    • B2 - Screenshot operation succeeded but a client error occurred (line 4 is blank).
  • [Game] - The abbreviation of the game's name that is used internally by PunkBuster.
  • [Map] - The name of the map that was running on the server at the time the screenshot was taken. The perspective of the player should be from this map, otherwise cheating should be suspected.
• Line 2
  • [SerialNumber] - The internal serial number associated with this screenshot which is part of the server log. Note that this is not the same as the serial number in the file name of the screenshot.
  • [ServerIP] - The IP address and port number of the server on which the screenshot was taken.
  • [ServerName] - The name of the server (as would be seen in the server browser) on which the screenshot was taken.
• Line 3
  • [GUID] - The player's 32-character globally-unique player identifier (GUID) is enclosed on either side with asterisks. If the GUID is not available because player authentication was not yet completed, it is replaced with a question mark. In these cases, the GUID is likely to be present in the accompanying screenshot log file, even if it is not present on the screenshot itself.
  • [PlayerName] - The name of the player, as would be seen in-game.
• Line 4
  • [AW] - The attempted width is equal to the value of the PB_SV_SsWidth setting.
  • [AH] - The attempted height is equal to the value of the PB_SV_SsHeight setting.
  • [XPct] - Equal to the value of the PB_SV_SsXPct setting.
  • [YPct] - Equal to the value of the PB_SV_SsYPct setting.
• Line 5
  • [RW] - The resulting width. See below for an explanation.
  • [RH] - The resulting height. See below for an explanation.
  • [SR] - Equal to the value of the PB_SV_SsSRate setting.
  • [UNK] - One of the following values: (1)/(2)/(3) is printed here. Leading us to believe, the number is likely the sequence of queued up screenshots.

The "Resulting" Line

The resulting width and height of the image are the actual end-product dimensions of the image which is seen in the PBSS. These will be different from the attempted width and height if any of the following conditions exist:

• The sample rate is greater than one, meaning the actual number of pixels captured is less than the number of pixels in the total box size.
• The attempted width and height values together created an image whose pixel count was greater than the limit of 82,000 (and the resulting image had to be resized to fit).
• The total pixel count in the box did not result in a number which formed a full rectangle, and the box needed to be resized to fit.

Errors

If for some reason, the screenshot capture operation failed, the area in the top part of the screenshot will be black and there will be an error message displayed in lines 4 and 5 of the information section. Usually, the status code will also change to B0 as well. The most common error you are likely to see is Application Not Active which indicates that the player's game was minimized or another application had focus.

There are also errors that may be present if the screenshot image itself was not returned properly, which would be in the accompanying log file. If a screenshot is only partially uploaded, it will be corrupted and cannot be viewed. In some cases, the player will timeout before the screenshot can be sent to the server and there will be an appropriate error message for that as well.

Handling Screenshot Files

The PunkBuster Screenshot is saved in PNG format and must not be altered in any way (including re-saving it in another format). This is because within the PNG file is some meta-data which provides verification information for the screenshot, which is compared to information from the streaming server log to ensure that the screenshot is genuine when it is submitted. If you re-save the file, the meta-data will either be altered or lost and will no longer match the information from the server log, thus rendering it unusable for MBL verification purposes.

If you wish to submit a screenshot, be sure that you do not alter it in any way once you save a copy of it from your server.

Client Screenshots

In addition to the PunkBuster Screenshots taken by a game server, there is a less-commonly used function in the Screen Capture Facility which allows clients to take their own PunkBuster Screenshots of themselves, which are then saved by default in their local pb/scrnshot folder. This involves the following client commands:

• PB_GetSs - Captures a PunkBuster Screenshot of one's own screen.
• PB_SsOptions - Shows or sets the current local options for taking client screenshots.

Client screenshots are saved with file names in the following format: [MM][DD]_[SSS].png where [MM] is the two-number representation of the month, [DD] is the two-number representation of the day, and [SSS] is a serial number. Line 2 of the screenshot information section does not include any server information, but instead shows the following: Player: [YYYY].[MM] where [YYYY] is the four-number representation of the year.

The usefulness of this function is generally limited to self-testing.

Category: Server Guides