OOTPB XML File Overview

battists · 05-30-2006, 02:24 PM

Hello and welcome everyone.

We're planning on releasing a detailed customization manual that will include lots of information on how to customize in-game text in OOTPB. However, that's not quite ready to be released yet. So, in the interests of keeping everyone happy in the mean time, here is some information to help get you started:

The Basics
OOTPB has a customizable text system that gives you the ability to modify much of the text that appears in the game. The customizable text is all stored in a text file in XML format, and can be edited with any text editing program.

What Can I Change?
In general, news articles/personal messages and play-by-play text are editable. In both cases, however, there are some hard-coded events that cannot be changed in this version of OOTPB.

Where is the Text Stored?
All of the in-game text is stored in a file called "english.xml." If you installed the program in the default location, this file can be found in the c:\program files\sports interactive\OOTP Baseball 2006\data\text directory.

What is an XML File?
Without getting too technical, an XML file is a specially-formatted text file somewhat similar to HTML. If you have some sort of text-editing program, you can modify this file. Luckily, every operating system has at least one text editing program by default (Notepad, Word Pad, Write, etc.)!

Is the File League-Specific?
There is one XML file that is used throughout all of your games. However, because the file is loaded each time you start the game, you can always swap different copies of the files in and out. For example, if you have one version that has old-school play-by-play, you could swap that in when simming your 1950s league, and then replace it with a more modern-sounding file when playing a new fictional league.

----

OK, that was the most basic information. Let's get into a little more detail on how OOPTB's XML file works. There are four concepts you need to understand in order to grasp the XML file: categories, objects, tokens, and conditions.

Categories
OOTPB 2006 has over 350 "categories." A category is called by the game's code whenever certain situations occur. Simply put, each category represents an "event" in your baseball universe. Here are some examples of text categories:

GAME_NEWS_SHUTOUT - Used by the game to create a news message when someone pitches a shutout
PLAYER_CONTRACT_REACTION_TOO_FAR_FROM_FAMILY - Used by the game to create a response from a player during contract negotiations, if he feels the job is too far from his home.
BATTER_OF_YEAR_SUBJECT - Used as the subject (not the body) of a message when a batter of the year is selected
ADVANCE_BASE_2 - Used in play-by-play when a player advances safely to second base

Categories are represented in the XML file with numeric identifiers, like this:

TEXT_CATEGORY id="13"

Since categories are only used when called by the game's code, please note that there will be no way for players to add new categories to the game.

Objects
Each category contains one or more "objects" that belong to that category. Each object represents one possible phrase to be used when that category is needed. For example, for ADVANCE_BASE_2, some objects might be:

"Wouk advances to second"
"Wouk reaches second safely"
"Wouk goes to second"

The more objects exist for a given category, the less likely you are to see the same phrase repeated over and over again. Objects are also represented in the XML file with numeric identifiers, but as a sub-set of categories, like this:

TEXT_CATEGORY id="13"
TEXT_OBJECT id="28" text="[%personname L] advances to second base"

Unlike categories, objects can be customized to your heart's content. There is no limit on the number of objects allowed per category, or total objects overall. The only requirement is that each must have a unique numeric ID.

Tokens
In the above example, we showed a player's name, Herman Wouk. So how does the game know which player name to use? This is where it gets a little technical. The XML file uses a set of variables called "tokens" to represent data from the game. Tokens are special keywords identified by brackets and a % sign. In the example above, [%personname L] is a token. Each token has a certain "meaning." In this case, [%personname L] is the last name of the player involved in the play. So, if it's Herman Wouk who just reached second, the game replaces [%personname L] with "Wouk."

There are over 300 tokens available in the game, and they can be mixed and matched to make creative news messages. 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 of 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.

As with the text categories, new tokens cannot be added by players, but a list of viable tokens and their usage will also come with the game. Not all tokens can be used with each category, either. Only certain information is provided to each category.

Line Breaks in Text Objects
Additionally, although it is not a token, entering the characters "(nl)" will cause the game to create a new line in the text (similar to a <br> in HTML code). For example:

Battisti said,(nl)(nl)"I just feel good about my swing right now."

This code would create the following text:

Battisti said,
"I just feel good about my swing right now."

Typically, two (nl)s work best together.

Random Usage
So, how does OOTPB 2006 choose which text message to use within a category? When you launch the game, the game will randomize each category. In other words, if there are 10 objects in the ADVANCE_BASE_2 category, those 10 will be randomized. The first time the game needs to use the ADVANCE_BASE_2 category, it will pick the first object from that randomized list. The second time, it will pick the second object, and so forth, eventually starting over at the beginning once it has cycled through all of the options. Each time you quit and reload the game, the lists are re-randomized.

Conditions
But that's not all! Markus has added another capability that expands the customization possibilities even further: conditions. Conditions define specific criteria that must be met before a text object can be used. By default, all text messages can be used at any time. This makes writing objects difficult, because the messages need to be fairly generic. For example, you shouldn't write, "Veteran Marc Duffy slugged three homeruns today," because it would sound out of place to say "veteran" if the game chose to use that message in a case where the person who hit the homeruns was a 19-year old rookie phenom.

Conditions are assigned, if needed, to each text object, and they help text writers add more flavor. For example, if we add the text condition "PERSON_AGE_MIN=35" to an object, then that object will only be used if the player selected is 35 years or older. If the game picks this object when it's trying to write a message for a 19-year old, it will simply skip the object and try the next one, repeating the process until a valid object is found. Objects can also have multiple conditions. Some examples of conditions are:

PERSON_AGE_MIN (Minimum age of the player)
PLAYER_IS_UPCOMING_FREE_AGENT (1 = yes, 0 = no)
CONTRACT_OFFER_IS_EXTENSION (1 = yes, 0 = no)
PLAYER_GREED_MIN (1=not greedy - 5=extremely greedy)

To see how these could work in conjunction, you could do something like this (I'll leave out the tokens to make it easier to read):

Example 1
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!

Example 2
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 imagine, that makes for some pretty complex possibilities! There are over thirty conditions available in the game.

As with the other aspects of the XML file, conditions are represented in the XML file with unique numeric identifiers, except that they also have a value parameter, like this:

TEXT_CONDITION id="7" value="34"

Conditions, like categories, need to be pre-programmed into the game. Therefore, it is not possible for users to create custom conditions.

05-30-2006, 02:24 PM	#1
battists Hall Of Famer Join Date: Jul 2004 Posts: 18,506 Blog Entries: 7	OOTPB XML File Overview Hello and welcome everyone. We're planning on releasing a detailed customization manual that will include lots of information on how to customize in-game text in OOTPB. However, that's not quite ready to be released yet. So, in the interests of keeping everyone happy in the mean time, here is some information to help get you started: The Basics OOTPB has a customizable text system that gives you the ability to modify much of the text that appears in the game. The customizable text is all stored in a text file in XML format, and can be edited with any text editing program. What Can I Change? In general, news articles/personal messages and play-by-play text are editable. In both cases, however, there are some hard-coded events that cannot be changed in this version of OOTPB. Where is the Text Stored? All of the in-game text is stored in a file called "english.xml." If you installed the program in the default location, this file can be found in the c:\program files\sports interactive\OOTP Baseball 2006\data\text directory. What is an XML File? Without getting too technical, an XML file is a specially-formatted text file somewhat similar to HTML. If you have some sort of text-editing program, you can modify this file. Luckily, every operating system has at least one text editing program by default (Notepad, Word Pad, Write, etc.)! Is the File League-Specific? There is one XML file that is used throughout all of your games. However, because the file is loaded each time you start the game, you can always swap different copies of the files in and out. For example, if you have one version that has old-school play-by-play, you could swap that in when simming your 1950s league, and then replace it with a more modern-sounding file when playing a new fictional league. ---- OK, that was the most basic information. Let's get into a little more detail on how OOPTB's XML file works. There are four concepts you need to understand in order to grasp the XML file: categories, objects, tokens, and conditions. Categories OOTPB 2006 has over 350 "categories." A category is called by the game's code whenever certain situations occur. Simply put, each category represents an "event" in your baseball universe. Here are some examples of text categories: GAME_NEWS_SHUTOUT - Used by the game to create a news message when someone pitches a shutout PLAYER_CONTRACT_REACTION_TOO_FAR_FROM_FAMILY - Used by the game to create a response from a player during contract negotiations, if he feels the job is too far from his home. BATTER_OF_YEAR_SUBJECT - Used as the subject (not the body) of a message when a batter of the year is selected ADVANCE_BASE_2 - Used in play-by-play when a player advances safely to second base Categories are represented in the XML file with numeric identifiers, like this: TEXT_CATEGORY id="13" Since categories are only used when called by the game's code, please note that there will be no way for players to add new categories to the game. Objects Each category contains one or more "objects" that belong to that category. Each object represents one possible phrase to be used when that category is needed. For example, for ADVANCE_BASE_2, some objects might be: "Wouk advances to second" "Wouk reaches second safely" "Wouk goes to second" The more objects exist for a given category, the less likely you are to see the same phrase repeated over and over again. Objects are also represented in the XML file with numeric identifiers, but as a sub-set of categories, like this: TEXT_CATEGORY id="13" TEXT_OBJECT id="28" text="[%personname L] advances to second base" Unlike categories, objects can be customized to your heart's content. There is no limit on the number of objects allowed per category, or total objects overall. The only requirement is that each must have a unique numeric ID. Tokens In the above example, we showed a player's name, Herman Wouk. So how does the game know which player name to use? This is where it gets a little technical. The XML file uses a set of variables called "tokens" to represent data from the game. Tokens are special keywords identified by brackets and a % sign. In the example above, [%personname L] is a token. Each token has a certain "meaning." In this case, [%personname L] is the last name of the player involved in the play. So, if it's Herman Wouk who just reached second, the game replaces [%personname L] with "Wouk." There are over 300 tokens available in the game, and they can be mixed and matched to make creative news messages. 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 of 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. As with the text categories, new tokens cannot be added by players, but a list of viable tokens and their usage will also come with the game. Not all tokens can be used with each category, either. Only certain information is provided to each category. Line Breaks in Text Objects Additionally, although it is not a token, entering the characters "(nl)" will cause the game to create a new line in the text (similar to a <br> in HTML code). For example: Battisti said,(nl)(nl)"I just feel good about my swing right now." This code would create the following text: Battisti said, "I just feel good about my swing right now." Typically, two (nl)s work best together. Random Usage So, how does OOTPB 2006 choose which text message to use within a category? When you launch the game, the game will randomize each category. In other words, if there are 10 objects in the ADVANCE_BASE_2 category, those 10 will be randomized. The first time the game needs to use the ADVANCE_BASE_2 category, it will pick the first object from that randomized list. The second time, it will pick the second object, and so forth, eventually starting over at the beginning once it has cycled through all of the options. Each time you quit and reload the game, the lists are re-randomized. Conditions But that's not all! Markus has added another capability that expands the customization possibilities even further: conditions. Conditions define specific criteria that must be met before a text object can be used. By default, all text messages can be used at any time. This makes writing objects difficult, because the messages need to be fairly generic. For example, you shouldn't write, "Veteran Marc Duffy slugged three homeruns today," because it would sound out of place to say "veteran" if the game chose to use that message in a case where the person who hit the homeruns was a 19-year old rookie phenom. Conditions are assigned, if needed, to each text object, and they help text writers add more flavor. For example, if we add the text condition "PERSON_AGE_MIN=35" to an object, then that object will only be used if the player selected is 35 years or older. If the game picks this object when it's trying to write a message for a 19-year old, it will simply skip the object and try the next one, repeating the process until a valid object is found. Objects can also have multiple conditions. Some examples of conditions are: PERSON_AGE_MIN (Minimum age of the player) PLAYER_IS_UPCOMING_FREE_AGENT (1 = yes, 0 = no) CONTRACT_OFFER_IS_EXTENSION (1 = yes, 0 = no) PLAYER_GREED_MIN (1=not greedy - 5=extremely greedy) To see how these could work in conjunction, you could do something like this (I'll leave out the tokens to make it easier to read): Example 1 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! Example 2 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 imagine, that makes for some pretty complex possibilities! There are over thirty conditions available in the game. As with the other aspects of the XML file, conditions are represented in the XML file with unique numeric identifiers, except that they also have a value parameter, like this: TEXT_CONDITION id="7" value="34" Conditions, like categories, need to be pre-programmed into the game. Therefore, it is not possible for users to create custom conditions.