How to write live game commentary files

• How to create a live game commentary file
  • Name convention and syntax
  • Simple commentaries
  • Conditional commentaries
  • Advanced commentaries
  • Priorities
  • List of tokens and events
    • Basic tokens
    • Team tokens
    • Player tokens
    • Stats tokens
    • Miscellaneous tokens
    • Events

Last updated: 12/18/2008

Howtos:

• Overview
• Countries
• Leagues
• Cups
• Player names
• Teams
• Live game commentary
• News
• CPU strategies
• Tags reference
• Download current definitions

How to create a live game commentary file

A live game commentary file is an xml file containing commentary strings for the live game in Bygfoot. The live game consists of several events, all of which need separate commentary.

You can get an archive with the current commentary files here.

Name convention and syntax

Live game commentary files have to have a file name like lg_commentary_lang.xml, with lang being a language shortcut, e.g. en or de.

There are only a few tags in the file (see also the tags reference): <lg_commentary> is the root tag, <event> describes an event; an event contains a <name> and several <commentary> entries.

<commentary> can have two attributes: cond and pri. The latter means priority; a commentary with high priority value relative to the rest of the commentaries for the given event is more likely to get chosen. cond means condition; we're going to see how to handle those later.

To write a new commentary file it might be best to copy one of the existing ones and replace/translate/extend the commentaries in the file.

Here's an excerpt from the lg_commentary_en.xml file:

  <lg_commentary>
    <event>
      <name>general</name>
      <commentary>_P1_ feeds the ball through to _P0_</commentary>
      <commentary>_P1_ threads a great ball to _P0_ </commentary>
      <commentary>Lovely pass from _P1_ releases _P0_</commentary>
      
      ...snip...
  
      <commentary>_P0_ spins past his marker</commentary>
    </event>
    <event>
      <name>lost_possession</name>
      <commentary>_P0_ wins the ball with a perfectly timed challenge</commentary>
      <commentary>Bad control by _P1_ lets _P0_ steal the ball off him</commentary>
      <commentary>_P0_ takes the ball away from _P1_ with a sliding tackle</commentary>
      <commentary>Loose ball falls to _P0_</commentary>
    </event>
  
    ...snip...
  
  </lg_commentary>

As you can see the tags are really simple. Now what are those weird _P0_ things about?

Simple commentaries

We call those things 'tokens'. They get replaced by player names and such when the commentary is actually generated. The list of available tokens is at the bottom of this page, as is a list of events.

To write a simple commentary, you just take a look at the events list to see which tokens are available for the event and let your imagination run. You could write for a goal event for instance

  <commentary>_P0_ scores! He already shot _PLGOALS0_ in the _LEAGUECUPNAME_!</commentary>

This would lead in the live game to something like 'Jeremy scores! He already shot 5 goals in the FA Cup!'.

There are events for which the tokens available vary; e.g. in a general event, there might be two players involved (one passing to the other) or only one (after a player took away the ball from his opponent). This shouldn't worry you at all. Just write commentaries for both cases, and when only one player is available only commentaries featuring one player token get considered.

Conditional commentaries

Let's take a look what the cond attribute in the commentary tag is for.

You might want to write commentary particularly suited for some situations. E.g. if a lot of goals get scored in a match, you want to exclaim 'My god! 7 goals within 50 minutes!'.

To be able to write this kind of commentary you need to specify a condition in the commentary tag. You can use all numeric tokens from the token list (ie. tokens with integer value). To write a commentary like the one above you'd write

  <commentary cond="_GOALS0_ + _GOALS1_ >= 6">_P0_ scores! We have incredible [_GOALS0_ + _GOALS1_] goals in this match!</commentary>

As you can see, if you want the program to perform some arithmetic operation in the commentary text, you have to enclose the expression in square brackets: [_GOALS0_ + _GOALS1].

Now this is a very simple condition. Not only >=, >, <, = and != may be used, but also and and or to create more complex expressions. and bind stronger than ''or'', so '1 < 2 and 2 < 2 or 3 < 4' would evaluate to FALSE (= 0).

So to have a more complex commentary you might write

  <commentary cond="_GD_ >= 2 and _GD_ < 4 and _MT_ > 60">_TL_ is _GD_ goals behind but there are still _MT_ minutes to go</commentary>

Advanced commentaries

Sometimes one would like to express, 'If one of the teams has 70% possession then write "Team TEAM is dominating the match."', with TEAM the appropriate team name. Now one could achieve this by writing

  <commentary cond="_POSS0_ >= 70">_T0_ is dominating the match</commentary>
  <commentary cond="_POSS1_ >= 70">_T1_ is dominating the match</commentary>

This would work, but it's a bad solution. We'd have to write two or three commentaries leading to the same text.

The more elegant way is to take advantage of the properties of the tokens. You've seen there are a lot of tokens ending with 0 and 1. But 0 and 1 are also the two possible outcomes when evaluating a condition. And 0 and 1 are the possible values for the ball possession token _POSS_, as well.

Here's a simple example: You want to have the name of the team that's in possession of the ball. You just write _T_POSS__. Easy. Given that the home team is in possession, this becomes _T0_ and then the name of the home team.

Another example: You want to have the name of the team leading (let's suppose that the result isn't a draw and ignore that a convenience token for this, _TL_ already exists). You just write _T[_GOALS1_ G _GOALS0_]_. (Note that here we need the brackets because an expression -- arithmetic with + and - or logical or both -- has to be evaluated.)

G stands for greater than; if you want less than you have to write L. We can't use > and < because those are special XML characters. Instead of <= and >= you have to write LE and GE (less or equal and greater or equal). Take care to leave a space before and after G and L.

Why does this work? There are two possibilities (remember that we suppose we don't have a draw): home team is leading or away team is leading. If the first is the case, the expression evaluates to FALSE (= 0), because the home team has more goals; so we'll get _T0_ after the evaluation is done. If the second is the case, the expression evaluates to 1, so we get _T1_. In both cases we get the name of the leading team. Great, isn't it?

Now you can use these tricks with all numerical tokens. To create an elegant solution for the problem about ball possession you can write

  <commentary cond="_POSS0_ >= 70 or _POSS1_ >= 70">_T[_POSS1_ GE 70]_ is dominating the match</commentary>

It is also possible to do this in conditions. E.g. if a team leads with more than 3 goals, we want to have a commentary like 'What a shame for TEAM', with TEAM being the losing team. But what if it's a national cup match, and the losing team is three leagues lower than the other team? Then it isn't a shame, such a result is to be expected. Here we need the method described above to create a condition that covers this case:

  <commentary cond="_GD_ > 3 and _TLAYER[_GOALS1_ > _GOALS0_]_ >= _TLAYER[_GOALS1_ < _GOALS0_]_">_RE_, what a shame for _TL_</commentary>

_TLAYER[_GOALS1_ > _GOALS0_]_ evaluates to the league layer of the leading team and _TLAYER[_GOALS1_ > _GOALS0_]_ becomes the layer of the losing team, so the commentary only gets considered if the losing team is at least on the same league level as the winning team.

We can use here < and > because in attributes it's allowed.

Priorities

Sometimes we want to make it very probable that a commentary gets chosen. E.g. if a player gets a yellow card and is automatically banned for the next match, we'd almost always like to have the commentary '_P1_ will be banned for the next _LEAGUECUPNAME_ match'.

To achieve this, we give a high priority value to the commentary:

  <commentary cond="_PLYELLOWS_ = _YELLOWLIMIT_" pri="10">_P1_ will be banned next _LEAGUECUPNAME_ match.</commentary>

The priority value increases the probability if it's high relative to the other commentaries. If the rest of the yellow card commentaries have priority 10, too, they all have the same probability.

List of tokens and events

Basic tokens

Team tokens

Player tokens

Stats tokens

All of these have a variant for the home team (those ending with a '0') and for the away team (ending with '1'). Only the home team tokens are listed, just replace the '0' with the '1' to get the stat value for the away team.

Miscellaneous tokens

Events

Let's see which events there are (their <name>) and what tokens they are allowed to contain (the tokens that are always available -- see above table -- aren't mentioned):