Page 1 of 2

[Tutorial] ManiaLinks Forever

Posted: 18 Oct 2008 14:29
by FT»Marcel
ManiaLinks Forever
An Introduction into the new Forever-ManiaLinks
(A Translation of the German ManiaLink Forever Tutorial)

Last Update:
04.12.2008 - New attribute added to Label: MaxLine
19.10.2008 - New attributes added: Scale and Looping

Overview about the Tutorial
  • Introducing words
  • Differences between the game versions
Positioning and Alignment
  • The two types of positioning
  • The third dimension
  • Small example
  • Effects of halign and valign
Overview about the new elements
  • <frame>Group several elements
  • <quad>Display pictures and shapes
  • <format>Global definition of formats
  • <label>Display text and buttons
  • <entry>Simple entry field
  • <fileentry>Entry field for file upload
  • <timeout>Avoid caching
  • <include>Import another XML file
  • <music>Output of background music (without buttons)
  • <audio>Output of a audio file (with Play/Stop buttons)
  • <video>Output of a video file
Interesting aspects in the end
  • Known issues
  • Combination of old and new ManiaLinks
  • Complex example
  • Direct linking via TMTP protocol
  • Multilangual ManiaLinks
  • Using parameters in ManiaLinks

Introducing words
With the Forever Addon, the structure of ManiaLinks has basically changed compared to TMU. Because of the new possibilities, the old narrow borders are broken up and you have much more flexibility in designing. Task of this tutorial is to explain you these new possibilities, so that you will be able to create a new Forever ManiaLink for your own.
The tutorial will start with a bit theory: Needed basic knowledge about the positioning of elements. After this, you will find in the second post a detailled description to each of the elements, including some examples. Finally I will mention some interesting aspects and give you a more complex example of a full (small) ManiaLink.
You can roughly say: There is no <line> and <cell> any longer, they are replaced by <quad>, <label> and <frame> which you can place whereever you want. But more about that later ^^
By the way: All old ManiaLinks created in TMU work in TMF, so don't panic. It is your part to decide, whether use the new ManiaLinks or stay at the old syntax.

What will not be explained in this tutorial:
  • The basical creation of a ManiaLink-File
    I will not describe, how to create a ManiaLink file and how to register it. Nothing changed in comparison to TMU, except the new PlayerPage, so you can look on other tutorials instead.
  • ManiaLinks for servers
    I will limit this tutorial to the ManiaLinks shown in the TMF Explorer. Special things in relation to Server ManiaLinks will not be mentioned.
The new PlayerPage
TrackMania Forever has a new PlayerPage:
Neither the page itself nor the way of registering a code has changed, except the new URL.
The old TMU PlayerPage has already been shut down, and you will not be able to use registered codes in TMU. In the end phase of the beta all codes has been transmitted to TMF, so that all old ManiaLinks are available.

United vs. Nations: Differences between the game versions
TMUF as a paid game offers the complete use of the ManiaLink features, as they are known from TMU.
But TMNF as the free Forever version has some limitations you should know:
  • No registered ManiaLinks
    TMNF players are neither able to register own ManiaLinks, nor to access other registered ManiaLinks. The ManiaLinks can only be visited by entering the complete URL of the XML-file. To make your ManiaLink fully compatible to TMNF, all links have to be done over the URLs.
    By the way: There is no Explorer menu entry in TMNF. You can open the Explorer by moving the mouse to the top border of the screen and by clicking the left icon ;)
  • No ManiaCodes
    TMNF players do not have the ability to use any ManiaCodes: The direct input of the URL was already denied in TMU, and access via registered codes is not supported, as said before. This means, that TMNF players cannot download any content from the ManiaLinks, even if it would be free (TMNF players have no Coppers). To say it directly: You can only stare on the ManiaLinks in TMNF ^^
  • Green is the world
    In the ManiaLinks, you can directly use the menu textures from the game (via styles, see below). Because the menus in TMNF are nearly all green, the styles of the ManiaLinks are green, too, whereas in TMUF they have different colors. But this limitation is a very small one in comparison to the others.
Notice: If you log in into TMNF with a TMUF account, you only have the third (small) limitation. The first two points are always related to the account type, and not to the game version.
The functionality of the elements is not affected by the game: TMNF players can use all the features of Entries and FileEntries and so on ;)

The root of all evil: Positioning and Alignment
In the Forever ManiaLinks, it is possible to place visual elements wherever you want. Because you'll need some basic knowledge about the positioning, I will explain the used methods in detail in this part.

Better safe then sorry: The two types of positioning
With the new Forever manialinks you can choose out of two positioning types: The classic one known from TMU with size of 2.0*1.5 and the new menu positioning which has a maximum size of 128*96.
A short preview concerning both methods:
  • Classic positioning:
    X interval: -1.00 ... +1.00 – the bigger the more left!
    Y interval: -0.75 ... +0.75 – the bigger the more top
    Z interval: -0.50 ... +0.50 – the bigger the more in the background
    Width interval: 0.0 ... 2.0
    Height interval: 0.0 ... 1.5
  • Menu positioning:
    X interval: -64 ... +64 – the bigger the more right
    Y interval: -48 ... +48 – the bigger the more top
    Z interval: -32 ... +32 – the bigger the more in the foreground
    Width interval: 0 ... 128
    Height interval: 0 ... 96
The main difference between the two methods is the interval of the values. Also mind the X- and Z-axis are mirrored in the classic positioning!
For positioning you need these attributes:
  • pos="X Y Z" and size="Width Height" for classic postioning
  • posn="X Y Z" and sizen="Width Height" for menu postioning
For menu positioning you simply add a "n" to the attribute. The values are separate by a space and stand between the quotation marks. You should stick to one positioning possibilty to avoid confusion. For example if a quad is positioned with pos="0.5 0.5 0" and another with posn="32 32 0" you will lose overlook.
The values depend on the main element. That means if a element is in a frame the values are relative to the position of the frame. If the element is written between the <manialink> tags the point of origin is the middle of the screen.

Could it be one more? The third dimension
Free positionable elements can overlap each other. Which is going to be overlaped by which one? For this you have the already mentioned Z value and the corresponding interval. These interval is only estimated so do not use it up to its end. Remember that big values are in the front in menu positiong but in the background in the classic positioning ;)
If two elements have the same Z value or if one element has an invalid (not in the valid interval) value the random will decide which element will be overlaped: Each acces to the ManiaLink can show another order! Therefore make sure to use clear and valid values.
As said, elements could be placed in a frame and a frame is an element itself. Each frame can have its own Z value. If an element is in a frame its Z value is the sum of its own Z value and the one of the frame, short: the sum of the single values is the new Z value.
A small example: You have a frame with the Z value 0.05. In that frame you have a quad with the Z value 0.2. The final Z value of the quad is 0.25, it overlaps all elements with a Z value bigger then 0.25.

Enough theory: A bit practise
Now it is time to show some code examples. The complete explanation will be found later, here all is about positioning.

Code: Select all

<quad pos="1 0.75 0" size="2 1.5" />
This quad orientates itself in the top left of the screen center (do not forget mirrored X axis) and has the size of the whole screen. It can be used as background for example.

The same is achived by this code:

Code: Select all

<quad posn="-64 48 0" sizen="128 96" />
Even this code creates a background started in the top left of the screen center but with the menu positioning.

Code: Select all

<quad sizen="20 20" />
The standart for pos(n) is "0 0 0", the middle of the screen or the positioning point of the frame, the element is in. This quad is near the middle of the screen. (Why not exactly is said in the next part.)

Code: Select all

<quad posn="20 20 0" />
If you leave out the size the standard values will be used. They are size="1 1" respectively sizen="64 64". You will get a square area with half the width of the screen.

Best is to use always pos(n) and size(n) so that the game has no chance for arbitrariness.
As a gimmick and to test the positioning I created a small script. With it you can test what changes if you change pos(n), size(n) and halign/valign on a quad. You can visit this script on the ManiaLink: [url=tmtp://]Test Quad[/url] (TMNF compatible)

The perfect confusion: Effects of halign and valign
If you understand all (at least a bit) it is time to bring some confusion: The alignment of the elements.
Some would say: with halign (horizontal alignment) and valign (vertical alignment) the alignment of the content is meant, for example in a label where the text should be displayed.
But it is not like that. Both aligns affect the alignment of the element itself. To show what is meant a picture:
With a view from outside you would say that the alignment is excactly the other way round: if you use valign="top" the quad is on the bottom, with halign="right" it is left.
But if you see it from the view of the quad it is logical: With halign/valign you define on which edge the positioning point is found, the point defined with pos(n). If we use bottom and left the positioning point is on the lower left edge of the quad. The standart values are halign="left" and valign="top". That means the positioning point is at default on the top left edge of the element.

Re: [Tutorial] ManiaLinks Forever

Posted: 18 Oct 2008 14:29
by FT»Marcel
Getting serious: The new elements of Forever ManiaLinks

A frame has the ability to group several elements of a characteristic area (e.g. the header) to bring a kind of structure in the ManiaLink code. To improve this structure, it is possible to interlace the frames.
The advantage of using frames is that all included tags orientate on its position: If you move the frame you will also move all included elements into the same direction. Consequently it is an easy way to move your navigation around while developing your design ;)
To make it clear: The frame creates a new point of origin on its own positioning point. The included elements orientate on this new point of origin, not on the center of screen ;)

  • pos(n)="X Y Z"Position of the frame

Code: Select all

<frame posn="20 20 0">
<quad posn="10 -10 0" />
This frame orientates itself in the top right of the screen center. All tags included orientate themselves on the point (20, 20, 0) as the new point of origin. If you want to take the quad out of the frame and have it to be on the same position as before you have to change ist coordinates from (10, -10, 0) to (30, 10, 0). Of course you can place more tags in the frame, but since simplify matters only one is shown in the example ;)

The quad is one of the new important elements in Forever ManiaLinks. It is used to place images on the ManiaLink and to react on the onMouseOver event (showing another image if the mouse is moved into the quad).
The quad is a stand-alone tag meaning that nothing is defined between <quad>-start and </quad>-end tag. For this XML has a shortform, write <quad ... /> instead of <quad ...></quad>. This works with all stand-alone tags ;)

  • pos(n)="X Y Z"Position of the quad
  • size(n)="width height"Size of the quad
  • scale="factor" - Scale factor for the quad
    With the scale factor you can define the real dimension of the quad. A value of "1" means the original size as given with size(n). If you write e.g. scale="2", the quad will displayed with double size in the end, as specified with size, a value smaller than 1 will reduce the size.
  • halign="left|center|right"Horizontal alignment
  • valign="top|center|bottom"Vertical alignment
  • image="image.jpg"Image URL
    As mentioned a quad is mainly used to display images. The image is adjusted to the quad size, it fills out the quad completely. Additional to the image formats allready supported in TMU .jpg, .tga and .dds TMUF supports .gif (256 colors, with a transparent color) and .png (24bit, with and without alpha channel).
  • imagefocus="image.jpg"Image URL for onMouseOver image
    If the mouse is moved into the quad this image will be displayed instead of the image declared with the image-attribute. The other way round changes the displayed image back to the first one.
    This only happens if you put a link on the quad, otherwise nothing will happen on onMouseOver.
  • style="CategoryName"Category name of the predefinied styles
  • substyle="StyleName"Name of the predefinied style
    With this two attributes style and substyle you can use the predefined styles included in TMF, like menu elements or buttons. Both attributes are needed to achieve one style. Remember that you cannot use style/substyle and image/imagefocus together, since they are responsible for the same feature (displaying images) and lock up each other.
    Smurf made a manialink on which all predifende styles for quads and labels are listed, see: [url=tmtp://]Example[/url]
  • bgcolor="RGBA"Uniform background
    With a quad you can display a uniform colored background. The value is conform to a 4 digit hexadecimal notation, like the textcolor attribute of the <format>-tag. The first 3 digits stand for the intensity of the colors: red, green and blue, whereas the last one indicates the transparency. Each digit must be in the range of 0..9 and A..F (like color formating in you nickname or in the chat with the difference the the transparency cannot be changed there).
    This attribute can also be used in the <format>-tag but it only affects <quad>-tags, others cannot be colored :(
  • url="externalHomepage.html"Link to a external page
  • manialink="ManiaLink"Link to a Manialink (registered code or URL)
  • maniazones="Maniazones-Link"Link to ManiaZones
    With these 3 attributes you can create a link, either to an external webpage (TMF minimizes and opens a browser window with the declared URL), to a ManiaLink or to ManiaZones (nothing known about that). Logically you only can use one of these 3 attributes ;)
  • addplayerid="1"Creates an identification link
    This attribut, set on "1", makes an identification link out of the link, that means you can access the data of the player added to the link. This can be used with PHP, following data is added:
    playerlogin=m4rcelAccount login
    lang=deLanguage of Trackmania Forever
    nickname=FT»MarcelNick name inclusive formating (special characters forged, e.g. » becomes %bb)
    path=World/Germany/Thuringia/ErfurtLocation specified in the profil (/ becomes %7c)
    With this information you can identify the player to give him access to special sections on your ManiaLink.
    A link would look like this: page.php?playerlogin=m4rcel&lang=de&nickname=FT%bbMarcel&path=World%7cGermany%7cThuringia%7cErfurt, page.php is the url specified with url, manialink or maniazones.
    Important hint: Unfortunately AddPlayerID is not as save as it seams. Indeed an identification of the player is possible, but this can easily be manipulated by entering the URL manuallay. Do not use it for critical sections!

Code: Select all

    pos="-0.5 0.25 -0.5" size="1.2 0.2"
This quad has the island header of the FT-forum as background. On onMouseOver it changes to the desert header. The file links to itself, which is placed on my local server, so I have not to type in the URL again and again :P The quad is placed top right of the screen center. With Z=-0.5 it is in the foreground.

Code: Select all

    posn="0 0 0"
    sizen="32 32"
This is the standart quad from the [url=tmtp://]quad-positioning-script[/url]. Here you see the usage of the predefinded styles. The combination of "Bgs1InRace" and "BgWindow” creates an rather dark rectangle with round edges.

The format tag as an non-visuall element groups several formattings which are used by different other elements. The format is used for the whole manialink or, if the format tag is placed in a frame, in frame and his subframes only.
Affected by this tag are the <label>, <entry> und <fileentry> tags, but they always can overwrite predefined formats with the same attributes.

  • textsize="Number"Text size
  • textcolor="RGBA"Text color
    Uses same color system like the <quad>-tag for the background.
  • style="StyleName"Name of the predefinied style
    Please note that only styles of labels can be used here, they differ from that ones of quads. What styles exist you can see on Smurfs manialink [url=tmtp://]Example[/url] for styles.
    Some styles, like CardButtons, affect the size of the label.

Code: Select all

<format style="TextValueSmall" />
With this all <label>, <entry> and <fileentry> tags get the TextValueSmall-format. In the same way you could set the text size and color.

The label is one of the new important elements. It is used to display text on the ManiaLink and overtakes the task of the old Text element. This means even longer texts are displayed using a label on Forever ManiaLinks.
Since the label is one of the elements which can make use of the format feature you can easily format your text style.
Another feature is the autotranslation of certain words within the label. Because of this the word "Statistics" is automatically translated depending the used language, e.g. in German into "Statistik". This only works with stand-alone-words, if there is only one character more it will not work. Which is quite usefull if it should not be translated on its own: only add a space.

  • pos(n)="X Y Z"Position of the label
  • size(n)="width height"Size of the label
  • scale="factor" - The scale facotr for the label
  • halign="left|center|right"Horizontal alignment
  • valign="top|center|bottom"Vertical alignment
    Both alignments influence the displayment of the text directly, it overtooks the alignments. The text oriantes as close to the positoning point as possible. So if the label has the settings bottom and center for the alignments the text will be centered at the bottom of the label. Regarding multiple line texts not each row is aligned on its own. All lines are positionated on one line (concerning halign).
  • text="Labeltext"The text of the label
    With this attribute you indicate the displayed text.
    Word-wrap within the text will cause a word-wrap on the manialink.
    Instead of <label text="LabelText" /> you can also write: <label>LabelText</label> (which looks like the old text element).
    The text can include all $-formatings.
  • autonewline="1"Activates auto word-wrap
    With this attribuet you can activate an auto word-wrap. With that to long lines are split up into more lines.
    Otherwiese the text will be displayed in one line and, if the text is too long, will be compress to the width of the label.
  • maxline="number" - Limits the maximum of displayed lines
    In relation with AutoNewLine you are able to limit the lines of text displayed in the Label. All lines exceeding the given number will be erased and not be visible.
  • url="externalHomepage.html"Link to a external page
  • manialink="ManiaLink"Link to a Manialink (registered code or URL)
  • maniazones="Maniazones-Link"Link to ManiaZones
    If no style is set the whole area of the label will become the link and not only the text. If the link is created the attribute autonewline will not work (a bug I allready reported in the beta)
  • addplayerid="1"Creates an identification link
    Additional information see attribute addplayerid in the Quad description
  • <format>-Attributes

Code: Select all

<label posn="-30 -20 5" halign="center" style="CardButtonMedium" text="$o$008White Button with darkblue Font" />
This label is displayed in the bottom left corner and has next to the predefined style some $-formats.

A key innovation of the new ManiaLinks is the ability to read the player's input and to process it in PHP-Scripts. You can use the "Entry" element for the input, which automatically inserts its value in the URL, where its name appears. As Quad the Entry element is a stand-alone tag, and contains no text between the tags.
An Entry accepts always strings, a possible restriction of the values must be done with the script, which could put out an error message for invalid values (e.g. if the value was not numeric).
It should be self-explanatory that an Entry element is only useful in a conjunction with a dynamic (script-based) ManiaLink. In the opposite a static (XML-based) ManiaLink is not able to respond to any input ;)

  • pos(n)="X Y Z" - The position of the Entry
  • size(n)="Width Height" - The size of the Entry
  • scale="factor" - The scale factor for the Entry
  • halign="left|center|right" - Horizontal alignment
  • valign="top|center|bottom" - Vertical alignment
  • name="EntryName" - The (unique) Name of the Entry
    In order to respond an input, the name of the Entry is important: If in any link this name occurs, it will be automatically replaced by the current value of this Entry. That is the reason why it is important that all Entries have unique names.
  • default="value" - The default value of the Entry
    This value is displayed in the Entry when you start the ManiaLinks. As long as the player does not change it.
  • autonewline="1"Enables the wordwrap
    AutoNewLine can be used for larger Entries. It is useful for each input which is bigger than only one line. It could be set in the Source with AutoNewLine. Without this claim the file will always show you the first line, also when you turn the enter key.
  • <format> attributes

Code: Select all

<entry posn="15 -8 5" sizen="5 2" style="TextValueSmall" name="inputvalue" default="42" />
<label posn="15 -1 -12 5" style="CardButtonMedium" text="Link with value" url="http://site.php?value=inputvalue" />
This Entry shows the value 42 when you open the ManiaLink. This value could be changed by the player at any time. If the player clicks on the label (which acts as a displayed button), "inputvalue" will automatically replaced by his command, and finally evaluated in the site.php.

It is like the name says: The FileEntry has the task to receive complete files and send them to a working script. If this element is clicked, a little window opens for the player. The player can choose in the window his file for upload. This action requires good knowledge of PHP, because finally the file must be received (POST method) and saved by the server. (At this point, my knowledge ends. I am not able to say anything more about it ^^)

  • pos(n)="X Y Z"The position of the FileEntry
  • size(n)="Width Height"The size of the FileEntry
  • scale="factor" - The scale factor for the FileEntry
  • halign="left|center|right"The horizontal alignment
  • valign="top|center|bottom"The vertical alignment
  • name="FileEntryName"The name of the FileEntry
    The name of the FileEntry has the same function like the name of the entry.
    For more information please look at the entry part of this tutorial.
  • folder="folderpath"The path of the folder at the top.
    The folder which you put in the value folder will be shown at first. It is also the highest folder which is available. The default folder is the TrackMania folder in your documents.
    Important hint: Without the value folder your TMF will crash! If you want to choose the default folder of TMF (the folder in your documents), use folder="" ;)
  • autonewline="1"Enables the wordwrap
    For more information for this value please read the entry part of this tutorial.
  • default="value"The standard value of FileEntry
    The default value of FileEntry has the same task as in Entry: This value is shown when opening the ManiaLink, and will be replaced after the player has chosen a file.
  • <format>-attributes

Code: Select all

<fileentry sizen="39 2" posn="16 -28 0" halign="left" style="TextValueSmall" name="avatarfilename" folder="skins\avatars" default="??"/>
<label posn="1 -32 0" halign="left" style="CardButtonMediumWide" manialink="POST(http://localhost/ManialinkSamples/UploadAvatar.php?file=avatarfilename,avatarfilename)" addplayerid="1" text="Post with playerid, target=manialink"/>
This code was taken from the ManiaLink example of Nadeo, which is available since Beta phase. This specified FileEntry starts in the "skins\avatars" folder, so that the player is only able to upload an avatar or any other file, which was previously saved in his avatar folder (local). The label shows you how the file will be send to a suitable script: With the help of POST() the file can be received by the script and saved on the server. (The AddPlayerID attribute is needed to generate a unique name for this file)

In TMU you had the problem, that ManiaLinks were cached, that means they were saved locally and on next call of this ManiaLink only the local copy was loaded instead of requesting it from the server again. In relation of dynamic ManiaLinks where content changes in rapid succesion this caching was a real problem. With help of header manipulations you could avoid this caching, but this way was not really nice ^^
Now you have the TimeOut tag: You have only to specify the time interval (in seconds) after which the ManiaLink should be reloaded from the server instead of using the cached copy of it. Using 0 as time interval means, that TMF will request the file from the server on each call of the ManiaLink.


Code: Select all

The two tags enclose a zero. Any questions? :D
With this piece of code you force TMF to reload the XML or PHP file from the server, so that possible changes will be applied with the next call of the ManiaLink without having to restart TMF. Use this code, if your ManiaLink is still under construction, so that you really can see all changes ;)

PHP coder already know the function of this tag: With help of Include you can import another XML file into the current one. This means that often used contents can be excluded into seperate files and in the special ManiaLinks you only have to insert the Include tag.
The file which should be included only needs the ManiaLink elements, without XML header or the <manialink>. See the including procedure as following: TMF cuts the XML file into two parts, and inserts the code of the external XML file 1:1 into this gap. So an additional <manialink> would be missplaced ;)
But there is a little bug, which I noticed already in the Beta phase: Only the first element of the external file is imported, all following elements are ignored by TMF. A little workaround is, to take all elements into an own frame, so that the frame is selected to be imported, and with it alle the other elements. Disadvantage: Because the music tag is not working in frames, this tag can only be important alone :(

  • url="inc.xml"File to be imported
ManiaLink file:

Code: Select all

<?xml version="1.0" encoding="utf-8" ?>
<include url="http://localhost/manialink/inc.xml"/>
File inc.xml:

Code: Select all

<quad posn="-20 -20 0" sizen="20 20" style="Bgs1InRace" substyle="BgWindow2" />
<quad posn="20 20 1" sizen="20 20" style="Bgs1InRace" substyle="BgWindow1" />
The main file only has the include element. To import both of the quads, you have to put them into a frame. Otherwise only the first quad would be visible, and the second one would be ignored.

Up to now, you had to use the audio element for playing some music in the background, which size was set to 0*0 for hidding the start/stop button. For this case there now is the <music> tag. After specifying the music file, which has to be in .ogg or .mux format, the music will be played without any visual displaying. A nice secondary effect: If you change the ManiaLink and the following ManiaLink has the same background music, it will go on without any break ;)
The music tag does only work, if it has the <manialink> directly as parent. If it is placed in a frame, you will hear the default menu music.
The best way is, to take the ManiaLink element to the end of the XML file, so the whole ManiaLink has been loaded before requesting the music file, which could be a bit bigger ;)

  • data="music.ogg"The music file

Code: Select all

<music data="http://localhost/manialink/alpine_race.ogg"/>
Simple function, simple code. You only have to specifiy the URL (here it is the Snow music from TMO) and it's done. (Because simple is simply simple :D)

One of the few elements, which work completely in the new structure of the Forever-ManiaLinks, is the audio tag. As known from TMU, you can play a music file with the audio. The difference betwenn <music> and <audio> is that the audio tag has a Play and Stop button, so the user can choose if he wants to hear it or not. The valid formats for <audio> are .ogg and .mux.

  • pos(n)="X Y Z"The postion of the Audio
  • size(n)="Width Height"The size of the Audio
    Because of the downward compatibility to TMU, you can choose to use width="Width" and height="Height" instead (Both only in classic positioning).
  • scale="factor" - The scale factor for the audio
  • data="audio.ogg"The audio file
    You can write the filename between the <audio>-tags as in TMU instead of using the attribute data.
  • play="1"Automatic start up when opening ManiaLink
    If the attribute play is set to "1", the audio file will start playing when the ManiaLink is opened.
  • looping="0" - Disable looping of the audio
    If looping is set to "0", the audio file will end after it played once. If set to "1" (default), it will play in an infinity loop.

Code: Select all

<audio pos="0 0 0" data="http://localhost/manialink/alpine_race.ogg"/>
The start button, displayed in the middle, will start playing the TMO Snow music when clicked

The video element is supported completely, too. It works almost like the audio element, only that it is displayed in another way (it is a video and not a music file ^^). The valid format for the video element is .bik.

  • pos(n)="X Y Z"The position of the video
  • size(n)="Width Height"The size of the video on the screen
    As in the audio tag, there are the two old elements for using: width="Width" and height="Height" (Both only in classic positioning)
  • scale="factor" - The scale factor for the video
  • data="video.bik"The video file
    Instead of using the data attribute, you can write the filename between the <video>-tags, as it was in TMU.
  • play="1"Automatic start on opening the ManiaLink
    If the attribute play is set to "1", the video will also be played on opening the ManiaLink.
  • looping="0" - Disable looping of the video
    If looping is set to "0", the video will end after playing once, as it is with audio. Set to "1" (default) means repeating the video in an infinity loop.

Code: Select all

<video pos="0 0 0" size="0.512 0.256" data="http://localhost/manialink/sign_warning.bik" play="1"/>
With this code the SignWarning sign will be automatically begin to play when opening the ManiaLink.

Re: [Tutorial] ManiaLinks Forever

Posted: 18 Oct 2008 14:30
by FT»Marcel
Interesting aspects in the end

Too good to be true: Known issues
Just after the release of TMF the first problems occur. To avoid similar questions I will list the known problems here.
  • Quality of images depends on texture settings
    Unfortunatly the images on the ManiaLink are displayed in dependency on the texture settings made in laucher. In plain language: Only players who set the texture quality on "high" see the ManiaLinks in high quality, all lower settings will lead to disfigurement of the images.
  • AddPlayerID can easily be manipulated
    As mentioned in the description of this attribute concerning quads and labels it can be manipulated in an easy way: by entering the URL manually. Critical areas must be secured in a different way.
  • Complete crash if the attribute folder is missing in the FileEntry
    Also this problem is named as important hint in the attribute description. If you leave out the attribute folder you will see your desktop immediately after you opened the ManiaLink. Avoid this bug by writing folder="" into the tag ;)

Don't panic: Combination of old and new ManiaLinks
As said in the beginning the old manialinks are compatible to TMF. This leads to new possibilities:
  • Complete new ManiaLink:
    Of course you can build your ManiaLink with these new elements I presented to you.
  • Complete old ManiaLink:
    Who bans the old system? If you do not need the new possibilities you can make your ManiaLink completely in the old system.
    Secondary effect: The ManiaLink can also be viewed in TrackMania United!
  • Combinated ManiaLink:
    With the option of the "oldnew" (:D) ManiaLink you have the possibility to combine the easy table structure and the new elements.
    This is easier then it sounds. Just split up your ManiaLink into two parts. Build the old ManiaLink as usual, remember only basic tags will work. Then you add the new elements in the end or in the beginning.
    Thereby you can deal with the old ManiaLink part like a frame with the z-value: pos="X Y -0.04" or posn="X Y 2.56". in this way it is possible to place elements before or behind the old part.
Another hint: If you open a partially or complete new manialink in TMU you will see only the old part or nothing. There will be no error message in TMU.

Complex example
It's time to introduce a more extensive example of what we've learned so far. It's about the input windows on my quad-test-manialink. (Manialink: [url=tmtp://]Test Quad[/url]).
To give a better overview, I shortened the Manialink-URLs, therefor not all of the input values are submitted anymore.

Code: Select all

01 <?xml version="1.0" encoding="utf-8" ?>
02 <manialink>
03   <frame posn="-60 -10 5">
04     <label posn="25 -2 15" sizen="40 4" halign="center" style="TextTitle3" text="Input Window (Menu Mode)"/>
05     <quad  posn="25 -1 10" sizen="40 4" halign="center" style="Bgs1InRace" substyle="BgTitle3_4" manialink=""/>
06     <label posn="15   -6 5" halign="center" style="TextStaticSmall" text="$o$ff0Position:"/>
07     <label posn="15 -8.5 5" halign="right"  style="TextStaticSmall" text="$oX = "/>
08     <label posn="15  -11 5" halign="right"  style="TextStaticSmall" text="$oY = "/>
09     <entry posn="15 -8.5 5" sizen="5 2" style="TextValueSmall" name="inputx" default="0"/>
10     <entry posn="15  -11 5" sizen="5 2" style="TextValueSmall" name="inputy" default="0"/>
11     <label posn="35   -6 5" halign="center" style="TextStaticSmall" text="$o$ff0Size:"/>
12     <label posn="37 -8.5 5" halign="right"  style="TextStaticSmall" text="$oWidth = "/>
13     <label posn="37  -11 5" halign="right"  style="TextStaticSmall" text="$oHeight = "/>
14     <entry posn="37 -8.5 5" sizen="5 2" style="TextValueSmall" name="inputwidth"  default="32"/>
15     <entry posn="37  -11 5" sizen="5 2" style="TextValueSmall" name="inputheight" default="32"/>
16     <label posn="25   -15 5" halign="center" style="TextStaticSmall" text="$o$ff0Alignment:"/>
17     <label posn="25 -17.5 5" halign="right"  style="TextStaticSmall" text="$ohalign = "/>
18     <label posn="25   -20 5" halign="right"  style="TextStaticSmall" text="$ovalign = "/>
19     <entry posn="25 -17.5 5" sizen="10 2" style="TextValueSmall" name="inputhalign" default="left"/>
20     <entry posn="25   -20 5" sizen="10 2" style="TextValueSmall" name="inputvalign" default="top"/>
21     <quad  posn=" 7 -25.5 5" sizen="6 3" halign="center" image="" manialink=""/>
22     <quad  posn="43 -25.5 5" sizen="6 3" halign="center" image="" manialink=""/>
23     <label posn="25 -25 5" halign="center" style="CardButtonMedium" manialink="" text="Apply Values"/>
24     <quad  sizen="50 30" style="Bgs1InRace" substyle="BgWindow2"/>
25   </frame>
26 </manialink>
An ingame screenshot of how it looks like:

Okay,let's go.
  • Lines 03 and 25 - The outline frame
    These lines create an outline frame, containing the entire input window. The purpose of this frame is, that I can relocate all elements within this frame to my needs, just by changing the frame's attributes. Doing so, all elements within the frame will move accordingly, because they're positioned relative to the frame's own position.
    The frames' negative position values will place it at the left bottom of the screen.
  • Line 24 - The window itself
    The "quad" tag in Line 24 creates a little window, the one with the rounded egdes. It serves the sole purpose of visually joining all input fields and labels together.
    Because it has no position values of its own, it will automatically inherit the outline frame's values. The "sizen" value determines the final size of the little window. The quad uses the Bgs1InRace style and BgWindow2 substyle.
  • Lines 04 and 05 - The title bar
    The "label" and the "quad" tags are responsible for shiny green title bar within the window. Both elements overlay each other, centered precisely, and the quad's lower z-value will make it appear behind the label.
    The label utilises the "TextTitle3" style, showing the "Input Window (Menu Mode)" writing in bigger letters.
    The quad utilises the "Bgs1Inrace" style with the "BgTitle3_4" substyle, which is green coloured, in both TMNF and TMUF.
    In addition, the quad tag contains a manialink, pointing to the same .php file, but with new values (see line 23 for details)
  • Lines 06 to 08, 10 to 13 and 16 to 18
    These 9 labels are responsible for the description tags. Positioning so many labels properly can consume quite a lot of time, with lots of try'n'error involved.
    Each word has its own "label" tag, using the "TextStaticSmall" style. The headlines use an additional "$o" formatting tag to make them bold, and the "$ff0" tag to make them appear in yellow color.
  • Lines 09, 10, 14, 15, 19 and 20
    Each input value has its own input field, using "input" + variable as the name to describe the functionality of the input field. The values for the variables will be sent to the .php file in line 23.
    The "TextStaticSmall" style is responsible for the yellow and shadowed text in the input fields.
    While X, Y, Width and Height are numbered values, Halign and Valign will only accept the text values "left", "center" and "right", respectively "top", "center" and "bottom". (This limitations have to be checked in the PHP script.)
  • Line 23 - Button and submission of value entries
    Here you can see how the values are submitted to a script (in this case, it's the same script again). The values in the URL are automatically replaced with the values from the "name" input fields before.
    Note: multiple values are submitted by adding a "&" between them, although this character must be encoded as "&amp" for beeing properly interpreted by the PHP script.
    The line "index.php?type=menu&lang=en&x=inputx&y=inputy" would call the php script like this (with the default values of x = y = 0): index.php?type=menu&lang=en&x=0&y=0
    Changing the values in the input fields will change the values in the processed URL accordingly.
    The "CardButtonMedium" style creates a huge white button (with a predefined size), containing the "Apply values" writing.
  • Lines 21 and 22 - Language choice and images
    These 2 quads will display 2 flags, making it possible to chose the language of the interface. It requires the 'image' attribute, which points to an URL where the image is hosted (24-bit .png images are supported).
    I could've used an "imagefocus" attribute as well to create a "mouseover" effect, but I have decided not to.
    The tag's Manialink attribute points to the same URL, but with the language value of your choice (lang=de/en).

The ManiaClick: Direct linking via TMTP protocol
With the Forever Addon you now have the possibility to link your ManiaLinks, so that one single click is enough to call it (so it's a ManiaClick :D). The only thing you have to do is using the TMTP protocol for linking. If you have selected the option during installation, all TMTP links will be sent to TMF when clicking (maybe you have to confirm a message of the browser). If TMF is not still running, it will open itself with this link, and the transmitted content will be displayed.
The use of TMTP links is as simple as HTTP links. You have the following possibilities to link your ManiaLinks:
  • Call your ManiaLink with its full URL
    To call a ManiaLink with its complete URL, you have only to replace the http:// with tmtp://. After that, just type the domain and the folder structure, as it is known from normal HTTP-links.
    Example: [url]tmtp://[/url]
  • Call your ManiaLink with its registered code
    It is also possible to call a ManiaLink with its registered code. Because these codes are only supported in TMUF, this version of linking will not work in TMNF. To link a registered code, just type "tmtp:///:" before it. The three / are important, otherwise some broswers will add an ending / which makes the code invalid and will return in an error ingame. The third slash avoids this unwanted behaviour.
    Example: [url]tmtp:///:Marcel[/url]
    Pay Attention with Special Characters: Because they are encoded in URLs, linking with them will not work. For example a space will be changed to "%20", so that "tmtp:///:Test Quad" will be sent as "tmtp:///:Test%20Quad" to TMUF. Because this code does not exist, TMUF is not able to translate this TMTP-link correctly.
By the way: You can also use the TMTP protocol to join a server and other things. But this is not part of the Tutorial, so I left it away :D

Qu'est-ce qu'il a dit? Multilangual ManiaLink
It is possible to let the game select the suitable language on its own depending on the language the player set. The procedure is really basic: You create one file in which the single words, word groups or sentences are in different languages, the game selects the suitable one and shows it (respectively english is chosen if the suitable language is missing). Okay, it is not that easy because you have to stick to a certain syntax. The following example shows you the buildup of a multilanguage ManiaLink:

ManiaLink file:

Code: Select all

<?xml version="1.0" encoding="utf-8"?>

	<include url="http://localhost/manialink/lang.xml" />

	<label posn="-20 0 1" textid="example" />
	<label posn="-20 -10 1" textid="nadeo" />
	<quad sizen="10 5" imageid="img" />

Here you see the buildup of the multilanguage ManiaLink. Important aspects are the include which loads the language file as well as the labels and the quad. Instead of the attribute text TextID is used, the text is not directly given, only a key which will also be found later in the lang.xml, same in the <quad> with the imageid. Nothing special up to now.

Language file: lang.xml

Code: Select all

	<language id="de">
		<nadeo>Danke Nadeo für diese neuen ManiaLinks</nadeo>

	<language id="en">
		<nadeo>Thanks Nadeo for these new ManiaLinks</nadeo>
Here you see the language file for the languages German and English.
Each language is enclosed throug <language id="CODE"></language>, whereas CODE is the game specific language code. Later you will see a list of the supported languages. Within the language tags the IDs are used: You can choose the content of the opening < > and the closing </ > tag on your own. The value you choose there is also the ID you use in the corresponging tag to get the text or the image. The content of the ID-tags will be directly used as value for the attribute, which uses this ID. You can use as much IDs as you wish.

Some hints:
  • The choice of the ID
    An ID must start with a letter. Afterwards you can use also numbers and an underline. Generally you should avoid special characters (except _). All other would be against the XML-syntax.
  • Missing IDs in a language
    If an ID is not found in the language, the player uses, the game searches this ID in English language. If it is available there it will be used, otherwise nothing would be shown. The order is: Selected Language > English > Nothing. So make sure at least English is complete!
  • Special characters
    If you use special characters in the lang.xml (as normal text, not as ID!) you figure out they won't be displayed correctly. To avoid this you have to save the lang.xml UTF-8 encoded. This can be done in normal Saving-dialog.
Supported attributes
To use an ID, you have only to add "id" to the attribute. For example "text" simply will become "textid", "image" will be "imageid" and so on.
The following attributes supports multilanguage:
  • <quad> - image, imagefocus, url, manialink
  • <label> - text, url, manialink
  • <audio> - data
  • <video> - data
This list is based on own tests and is maybe not complete. If you find another supported attribute, just say it. Thanks to Konte, who gives an important hint for that ;)

List of language codes:
  • cz - Czech
  • de - German
  • en - English
  • es - Espanol
  • fr - French
  • hu - Hungarian
  • it - Italian
  • jp - Japanese
  • kr - Croatian
  • nl - Dutch
  • pl - Polish
  • pt - Portuguese
  • ru - Russian
  • sk - Slovak
  • zh - Chinese
I have not tested all these codes, but for this languages there are language files for the game. Therefore I think they will be supported on ManiaLinks ;)

Test?id=3: Using parameters in ManiaLinks
Together with kastun and Balmung I discovered the possibility, to give parameters to registerd ManiaLinks with which could be worked with a script. This very useful feature (in combination with PHP of course) should be explained in this part of the tutorial.
It is quite easy: PHP pros allready know it in this form: "" The parameter 15 is submited in the variable "id" to page.php. This could be transferred rather 1:1 to ManiaLinks.
Register the page as ManiaLink, without any parameters:
Code: "Page" => URL:
To acces the page with a paramter just visit Page?id=15. In this example you will get the value 15 with $_GET['id'].
That was all the magic: As on PHP files you can stick variables and values on ManiaLinks with ?. Remember more variables are added with & (in TrackMania this will be a normal &).

All good things must come to an end...
Now we reached the end of my Tutorial. I have said everything I wanted to say, alluded to everithing I wanted to allude. Now it is your part to use this knowledge. Present your new, or old, ManiaLinks and show what you are able to do now :D
Of course I will be happy about any comment and critics to this tutorial (after I received many of them to the German version). If you have any questions, post them, I think I will not be the only one who want to answer them ;)

Finally I want to thanks those of you, who supported me while writing this tutorial:
While writing the German version, the Betatesters answered me some questions to better understand the new ManiaLinks. To improve the quality, the FT and the ECU clan supported me with pointing on erronous, ununderstandable or just bad written parts. Thank you for that :)
After completing the German tutorial, I decided to translate it to English to view the knowledge to more than only Germans. I want to thank all you helped me with the translation: FT»Dany, CyR4S and TStarGermany.
Special thanks goes to ECU kastun. He did not only helped a lot while writing the German version, he also translated nearly the half of the tutorial and helped checking the translated parts. Without his support, the tutorial would never be as big and detailled as it is now. Thank you :)

That's it, now it's your turn.

Re: [Tutorial] ManiaLinks Forever

Posted: 18 Oct 2008 22:02
by Xymph
Excellent work. :thumbsup: I added it to my TMF hub page (where your German version was already linked).

Re: [Tutorial] ManiaLinks Forever

Posted: 19 Oct 2008 19:55
by FT»Marcel
Thank you :)

I have updated the tutorial:
* Added the Attribute Scale to all visual elements (I just saw it in the other thread)
* Added the Attribute Looping to <audio> and <video>. (I found this attribute when I had nothing else to do than searching the other attributes in the .exe ^^)
* Fixed few translation mistakes

Btw: Can maybe a moderator stick this thread on the top of the forum? It would be a waste if it will be flooded away :( Thanks ;)

Re: [Tutorial] ManiaLinks Forever

Posted: 21 Oct 2008 09:52
by Alinoa
great tutorial GG :wink:

Re: [Tutorial] ManiaLinks Forever

Posted: 21 Oct 2008 10:08
by Generator
Wow Marcel, Bet ya fingers ache after that lot lol!

Great tuto and Im bookmarking it now for future reference! (already got a manialink in progress but it still taught me a thing or two!) :thumbsup:

:gobananas: :gobananas: :gobananas:


Re: [Tutorial] ManiaLinks Forever

Posted: 27 Oct 2008 09:18
by jonthekiller
I am translate this tutorial in French here ... hp?t=30481

Thanks for your job Marcel :3

Re: [Tutorial] ManiaLinks Forever

Posted: 30 Oct 2008 13:21
by f*ckfish
Yeah, finally in English, good work, Marcel =)

Someone pleaaase sticky it ;-)

Re: [Tutorial] ManiaLinks Forever

Posted: 31 Oct 2008 09:26
by FT»Marcel
jonthekiller wrote:I am translate this tutorial in French here ... hp?t=30481

Thanks for your job Marcel :3
Thank you for translating the Tutorial into French, Now more TrackManiacs have the possibility to read it :)

But I have some requests:
Can you please add my Name at the beginning of the tut and link back to the original (German version) and to my clan?
(Maybe something like "Une traduction de l'allemand ManiaLink Forever Tutorial de FT»Marcel" (Don't know if this is correct French ^^)
URL to German Tutorial: ... hp?t=31416
URL to my Clan:

I think it is not obvious enough that I wrote the "original" version, so please at this information (and at least one of the two links) ;)

Another request: The meaning of "Qu'est-ce qu'il a dit?" in the English version is, to have a second language in the headline to point on the multilangual ManiaLinks. (btw: In german Tut, its "What he said?" ^^).
So I think it is better if you add a second language, too, to point again on the multilangual Manialinks.
Maybe German? "Was hat er gesagt? ManiaLink Multilingue" ;)

@ others:
Thank you for your nice words, it shows that the invested time was not wasted :thumbsup:

Re: [Tutorial] ManiaLinks Forever

Posted: 31 Oct 2008 17:51
by jonthekiller
OK, no problem, it is made.

Re: [Tutorial] ManiaLinks Forever

Posted: 02 Nov 2008 08:57
by FT»Marcel
Thank you :)

But I think you missunderstood me with the headline of the Multilang-MLs ^^

Only write:
Was hat er gesagt? ManiaLink Multilingue

I don't want to force you to use German, so that you can use another language if you know any. That's why the "Maybe German?" in the previous post as suggestion ;)

Btw: Thanks for sticky :)

Re: [Tutorial] ManiaLinks Forever

Posted: 02 Nov 2008 09:18
by jonthekiller
ok, lol

Re: [Tutorial] ManiaLinks Forever

Posted: 23 Nov 2008 22:23
by Knuk
I have a problem:
I have made a test for a manialink but nothing appears.
This is the code of the manialink:

Code: Select all

<?xml version="1.0" encoding="utf-8" ?> 
    posn="0 0 0"
    sizen="32 32"
Do i have made a error?
(the manialink page is knuknm)

Re: [Tutorial] ManiaLinks Forever

Posted: 24 Nov 2008 10:14
by w1lla

Code: Select all

<?xml version="1.0" encoding="utf-8" ?> 
<quad    posn="0 0 0"
    sizen="32 32"
Should work. ;)