| Find in this manual | ||
| Replace with | ||
Understanding the Text Database
There are four important concepts to understand when editing the text database: categories, objects, tokens, and conditions. In addition, there are a number of other small rules and tricks that are important in editing the text database. This section will describe these concepts in detail.
In the XML file, categories are represented by the TEXT_CATEGORY element. Each element has a unique numeric identifier, like this:
<TEXT_CATEGORY id='13'>
</TEXT_CATEGORY>
Categories themselves don't actually contain any text. They're simply, um, categories, that are then filled with text 'objects,' described in the next section.
A complete list of the categories, IDs, and their usage in Microsoft Excel format can be downloaded here. In this document, the categories have been further divided into logical groups: Game News, Manager News, Game Play-by-Play, League News, League Events, Player Season Descriptions, and Contract Negotiations. However, these groups are not actually used in the XML file, nor anywhere else in the game.
Remember that each TEXT_CATEGORY element must have the closing tag </TEXT_CATEGORY>.
Note: Since categories are used only when called by the game's code, please note that there is no way for players to add new categories to the game.
For example, for the ADVANCE_BASE_2 category, some of the objects might be phrases like these:
'Wouk advances to second'
'Wouk reaches second safely'
'Wouk goes to second'
In the XML file, objects are identified by the TEXT_OBJECT element. TEXT_OBJECTS are nested inside a TEXT_CATEGORY element, and each TEXT_OBJECT must have a unique numeric identity, like this:
<TEXT_CATEGORY id='13'>
?? <TEXT_OBJECT id='28' text='[%personname L] advances to second base'/>
</TEXT_CATEGORY>
Looking at the example above, we can see that TEXT_OBJECT 28 is part of TEXT_CATEGORY 13.
Remember that each TEXT_OBJECT element must end with a closing tag. In this case, instead of having a wholly separate tag, the tag is closed by ending the element with the characters />.
The more objects that exist for a given category, the less likely you are to see the same phrase repeated over and over again. By default, every text object that you create can potentially be used by the game. For that reason, it is important to make objects very generic, unless you are using conditions, described below. For example, let's say you create the following text object (tokens removed for simplicity):
After hitting .300 this month, Davis wins the Batter of the Month award. He really has a great career ahead of him!
If this object gets used with a young player, it will sound fine. But if the object is used when a 40-year-old wins the award, it will sound awkward, because he doesn't have a great career ahead of him. So, it's important to keep things generic if you aren't using conditions.
Unlike categories, objects can be customized to your heart's content. There is no limit to the number of objects allowed per category, or the total number of objects overall. The only requirement is that each must have a unique numeric ID. That is, you cannot have two TEXT_OBJECTS in the XML file with the same ID, even if they are in different categories.
[%personname L]
These pieces of text are known as 'tokens,' and they represent variables. For those of you unfamiliar with programming, tokens are used to represent pieces of information that will be pulled from the OOTPB game. There are over 300 tokens in OOTPB.
For example, let's say we're writing a few text objects to be used when a player makes a catch in the outfield. We don't know which player will be making the catch. So, how can we ensure that the game will show the correct player's name? We use a token. By putting the [%game fielder of] token into a text object, OOTPB will know to substitute the name of the player actually making the catch in the game.
Tokens are essential to editing text objects. Nearly every text object in the game uses at least one token. Tokens can be mixed and matched to make creative text objects. For example, you might see an object that looks like this:
The [%subleaguename] honored [%personlink] with the [%batteraward] earlier today. [%leagueyear] was a career year for the [%teamlink] [%playerposition], who posted a batting average of [%batting avg], with [%batting rbi word] and [%batting hr] dingers for good measure.
Wow! That's confusing! But when all those tokens are converted into real values by the game, you can end up with a message like this:
The National League honored Markus Heinsohn with the Super Slugger Award earlier today. 2006 was a career year for the Berlin first baseman, who posted a batting average of .355, with 145 RBI and 45 dingers for good measure.
A complete list of the available tokens and their usage in Microsoft Excel format can be downloaded here. There are also a few important things to remember regarding tokens.
However, there are two special rules governing link tokens.
Conditions are applied to text objects, and they influence when an object can be used. For instance, you can have an object that refers to a 'long-time veteran,' which gets used only if the player in question has been playing professional ball for more than 10 years. Some examples of conditions are as follows:
In the XML file, conditions are represented by the TEXT_CONDITION element. TEXT_CONDITION elements are nested inside a TEXT_OBJECT element, like this:
<TEXT_OBJECT id='2237' text='The [%personage]-year-old veteran [%playerposition] has a lifetime average of [%batting avg].'>
?? <TEXT_CONDITION id='7' value='34'/>
</TEXT_OBJECT>
Conditions also contain an ID number and a value. In the above example, TEXT_CONDITION 7 is the 'PERSON_AGE_MIN condition. Since the value is 34, this text object will be used only if the player is at least 34 years old. True/false conditions such as PLAYER_IS_UPCOMING_FREE_AGENT usually have a value of 1 if true, and 0 if false.
A complete list of the available conditions, IDs, values, and their usage in Microsoft Excel format can be downloaded here. There are also a few important things to remember regarding conditions. As with text categories, new conditions cannot be added by players, although more conditions will probably be added in subsequent versions of the game, to allow even greater flexibility.
A text object can have multiple conditions assigned. For example, you could combine the following conditions in one object:
CATEGORY = PLAYER_CONTRACT_EXTENSION_RUMOR
PERSON_AGE_MIN = 34
PLAYER_IS_UPCOMING_FREE_AGENT = 1
CONTRACT_OFFER_IS_EXTENSION = 1
OBJECT:
Cagey veteran Will Smith today downplayed rumors that he was negotiating an extension with the Phillies. He repeatedly dodged the issue, turning aside all questions with a laugh. The 34-year-old shortstop is in the last year of his contract, and is hitting .340 on the season, with 25 bombs. The Phillies need to wrap this guy up, or perhaps start looking for a younger solution!
Here is another example of a text object with conditions:
CATEGORY = PLAYER_CONTRACT_REACTION_NEGATIVE
PLAYER_GREED_MIN = 4
CONTRACT_OFFER_IS_EXTENSION = 0 (free agent contract offer)
OBJECT:
Are you kidding me with that offer? Money talks, and I'm hearin' nothin' over here. Pony up some more cash, and some more respect, or go look for another shortstop!
As you can see, conditions make the text engine much more flexible. Of course, the more specific your conditions are, the less likely they are to get used.
<TEXT_OBJECT id='11679' text='[%game batter] rounds third...(nl)returns to the bag...'/>
Many text objects in OOTPB will be one paragraph only. However, you can create multiple paragraphs within a single object by entering the text (nl), including the parentheses. (nl) stands for 'new line,' and unsurprisingly, the result in OOTPB is that any time you use the (nl) command, a new line is created in the text. It often looks best to use two (nl)s in succession, so that a blank line appears between the two paragraphs. For example:
[%personlink] won the award today!(nl)(nl)'I'm so happy!' he said.
This text object results in the following text on-screen:
Steve Battisti won the award today!
'I'm so happy!' he said.
A few more notes about (nl):
Categories
Text in the game is divided into 'categories,' each of which is called by the game's code whenever certain situations occur. Simply put, each category represents an 'event' in your baseball universe. OOTPB has over 350 categories. Here are some examples of text categories:| Category | Used... |
| GAME_NEWS_SHUTOUT | When a player pitches a shutout. |
| PLAYER_CONTRACT_REACTION_TOO_FAR_FROM_FAMILY | When a player turns down a contract offer because he feels the team is too far from his home. |
| BATTER_OF_YEAR_SUBJECT | As the subject header when a player wins the batter of the year award. |
| ADVANCE_BASE_2 | In play-by-play, when a player advances safely to second base |
<TEXT_CATEGORY id='13'>
</TEXT_CATEGORY>
Categories themselves don't actually contain any text. They're simply, um, categories, that are then filled with text 'objects,' described in the next section.
A complete list of the categories, IDs, and their usage in Microsoft Excel format can be downloaded here. In this document, the categories have been further divided into logical groups: Game News, Manager News, Game Play-by-Play, League News, League Events, Player Season Descriptions, and Contract Negotiations. However, these groups are not actually used in the XML file, nor anywhere else in the game.
Remember that each TEXT_CATEGORY element must have the closing tag </TEXT_CATEGORY>.
Note: Since categories are used only when called by the game's code, please note that there is no way for players to add new categories to the game.
Objects
As we mentioned, categories don't actually contain text. However, each category contains one or more 'objects.' Each object represents one possible text phrase to be used when that category is needed. So, objects all belong to a single category.For example, for the ADVANCE_BASE_2 category, some of the objects might be phrases like these:
'Wouk advances to second'
'Wouk reaches second safely'
'Wouk goes to second'
In the XML file, objects are identified by the TEXT_OBJECT element. TEXT_OBJECTS are nested inside a TEXT_CATEGORY element, and each TEXT_OBJECT must have a unique numeric identity, like this:
<TEXT_CATEGORY id='13'>
?? <TEXT_OBJECT id='28' text='[%personname L] advances to second base'/>
</TEXT_CATEGORY>
Looking at the example above, we can see that TEXT_OBJECT 28 is part of TEXT_CATEGORY 13.
Remember that each TEXT_OBJECT element must end with a closing tag. In this case, instead of having a wholly separate tag, the tag is closed by ending the element with the characters />.
The more objects that exist for a given category, the less likely you are to see the same phrase repeated over and over again. By default, every text object that you create can potentially be used by the game. For that reason, it is important to make objects very generic, unless you are using conditions, described below. For example, let's say you create the following text object (tokens removed for simplicity):
After hitting .300 this month, Davis wins the Batter of the Month award. He really has a great career ahead of him!
If this object gets used with a young player, it will sound fine. But if the object is used when a 40-year-old wins the award, it will sound awkward, because he doesn't have a great career ahead of him. So, it's important to keep things generic if you aren't using conditions.
Unlike categories, objects can be customized to your heart's content. There is no limit to the number of objects allowed per category, or the total number of objects overall. The only requirement is that each must have a unique numeric ID. That is, you cannot have two TEXT_OBJECTS in the XML file with the same ID, even if they are in different categories.
Tokens
If you examine the XML file, you will see many phrases with text enclosed in brackets beginning with a % sign, like this:[%personname L]
These pieces of text are known as 'tokens,' and they represent variables. For those of you unfamiliar with programming, tokens are used to represent pieces of information that will be pulled from the OOTPB game. There are over 300 tokens in OOTPB.
For example, let's say we're writing a few text objects to be used when a player makes a catch in the outfield. We don't know which player will be making the catch. So, how can we ensure that the game will show the correct player's name? We use a token. By putting the [%game fielder of] token into a text object, OOTPB will know to substitute the name of the player actually making the catch in the game.
Tokens are essential to editing text objects. Nearly every text object in the game uses at least one token. Tokens can be mixed and matched to make creative text objects. For example, you might see an object that looks like this:
The [%subleaguename] honored [%personlink] with the [%batteraward] earlier today. [%leagueyear] was a career year for the [%teamlink] [%playerposition], who posted a batting average of [%batting avg], with [%batting rbi word] and [%batting hr] dingers for good measure.
Wow! That's confusing! But when all those tokens are converted into real values by the game, you can end up with a message like this:
The National League honored Markus Heinsohn with the Super Slugger Award earlier today. 2006 was a career year for the Berlin first baseman, who posted a batting average of .355, with 145 RBI and 45 dingers for good measure.
A complete list of the available tokens and their usage in Microsoft Excel format can be downloaded here. There are also a few important things to remember regarding tokens.
- As with text categories, new tokens cannot be added by players, although more tokens will certainly be added in subsequent versions of the game, to allow even greater flexibility.
- Only certain tokens can be used in each category. See the Excel document for details on which tokens are available to each category.
- Tokens must be placed in brackets [ ], not parentheses or braces. They also must start with a % sign. If a token is not spelled correctly (including the presence or absence of spaces), it will not work.
- Statistical tokens are dynamic, depending on the nature of the category. For example, if you use the [%batting hr] token in a Player of the Week award message, the token will display the number of home runs the player hit that week. If you use the same token in a Player of the Month award message, it will display the number of home runs the player hit that month.
Hyperlink Tokens
Some tokens for player and team names include the word 'link.' These tokens have special behavior in OOTPB. When a link token is used, that team or player name will be hyperlinked in the game. For example, if you use [%personlink], the result might be the name of a player, Steve Wilson. However, it will also be a hyperlink to Steve Wilson's player page within the game. We encourage you to use link tokens in all news messages.However, there are two special rules governing link tokens.
- Link tokens cannot be used in categories with the word SUBJECT in the title.
- Link tokens cannot be used in play-by-play.
Conditions
By default, every text object that you create can potentially be used by the game, so most objects should be fairly generic in nature. You don't want your article mentioning a 'young star' when it could be talking about an over-the-hill veteran. That problem alone would have made OOTPB's in-game text severely limiting. Luckily, however, OOTPB also includes 'conditions.'Conditions are applied to text objects, and they influence when an object can be used. For instance, you can have an object that refers to a 'long-time veteran,' which gets used only if the player in question has been playing professional ball for more than 10 years. Some examples of conditions are as follows:
| Condition | Used... |
| PERSON_AGE_MIN | When an object should be used only for players over a certain age. |
| PLAYER_MLB_YEARS_MAX | When an object should be used only for players with less than X years of major league experience. |
| PLAYER_IS_UPCOMING_FREE_AGENT | When you want the object to consider whether the player in question will be a free agent. |
| GAME_BASES_LOADED | In play-by-play, when an object should be used only if the bases are loaded. |
<TEXT_OBJECT id='2237' text='The [%personage]-year-old veteran [%playerposition] has a lifetime average of [%batting avg].'>
?? <TEXT_CONDITION id='7' value='34'/>
</TEXT_OBJECT>
Conditions also contain an ID number and a value. In the above example, TEXT_CONDITION 7 is the 'PERSON_AGE_MIN condition. Since the value is 34, this text object will be used only if the player is at least 34 years old. True/false conditions such as PLAYER_IS_UPCOMING_FREE_AGENT usually have a value of 1 if true, and 0 if false.
A complete list of the available conditions, IDs, values, and their usage in Microsoft Excel format can be downloaded here. There are also a few important things to remember regarding conditions. As with text categories, new conditions cannot be added by players, although more conditions will probably be added in subsequent versions of the game, to allow even greater flexibility.
A text object can have multiple conditions assigned. For example, you could combine the following conditions in one object:
CATEGORY = PLAYER_CONTRACT_EXTENSION_RUMOR
PERSON_AGE_MIN = 34
PLAYER_IS_UPCOMING_FREE_AGENT = 1
CONTRACT_OFFER_IS_EXTENSION = 1
OBJECT:
Cagey veteran Will Smith today downplayed rumors that he was negotiating an extension with the Phillies. He repeatedly dodged the issue, turning aside all questions with a laugh. The 34-year-old shortstop is in the last year of his contract, and is hitting .340 on the season, with 25 bombs. The Phillies need to wrap this guy up, or perhaps start looking for a younger solution!
Here is another example of a text object with conditions:
CATEGORY = PLAYER_CONTRACT_REACTION_NEGATIVE
PLAYER_GREED_MIN = 4
CONTRACT_OFFER_IS_EXTENSION = 0 (free agent contract offer)
OBJECT:
Are you kidding me with that offer? Money talks, and I'm hearin' nothin' over here. Pony up some more cash, and some more respect, or go look for another shortstop!
As you can see, conditions make the text engine much more flexible. Of course, the more specific your conditions are, the less likely they are to get used.
(nl): Creating New Lines
If you examine the XML file, you might see the (nl) combination of characters frequently, such as in this object:<TEXT_OBJECT id='11679' text='[%game batter] rounds third...(nl)returns to the bag...'/>
Many text objects in OOTPB will be one paragraph only. However, you can create multiple paragraphs within a single object by entering the text (nl), including the parentheses. (nl) stands for 'new line,' and unsurprisingly, the result in OOTPB is that any time you use the (nl) command, a new line is created in the text. It often looks best to use two (nl)s in succession, so that a blank line appears between the two paragraphs. For example:
[%personlink] won the award today!(nl)(nl)'I'm so happy!' he said.
This text object results in the following text on-screen:
Steve Battisti won the award today!
'I'm so happy!' he said.
A few more notes about (nl):
- (nl) cannot be used in SUBJECT categories.
- (nl) is case-sensitive. You cannot write (Nl) or (NL), or the text will appear in the game the way you typed it.
Other XML File Notes
In addition to the five topics covered above, there are a few more notes about the behavior of the XML file:- Be careful when writing text objects in Microsoft Word. Word has a tendency to replace apostrophes and quotation marks with its special 'curly quotes.' Curly quotes are not supported by OOTPB, and their presence will result in garbled characters in your news messages. Similarly, Word also likes to turn ellipses (...) into a special ellipsis character, instead of three separate periods. This ellipsis character is also not supported. These can both be toggled on and off in Word's Auto Correct options.
- There are a handful of other functions within the XML file that affect the usage chance for certain options and the mutual exclusivity of objects. These, however, all pertain to game play-by-play commentary and are covered in that section.
