Developer Notice: EOL Changes in Hg

Attention Ryzom Core Developers,

I've been spending an increasing amount of time developing on Linux using vi and have run into the ^M frustration enough that I decided to implement the Hg end-of-line extension. I converted the repository to use LF as the native line ending. You can alter what your local native is in your .hgrc or repository level .hg/hgrc file.

Everyone should enable the EOL extension in their Hg configuration file:

[extensions]
eol =

; Uncomment to change your local repository to CRLF for Windows
;[eol]
;native = CRLF

Here is the whole changeset if you want to see. It really is just a massive diff change CRLF to LF to nearly every file in the repository.

Please change your repository extensions and merge default into your branches as soon as possible!

Ryzom Core Buildings

Ryzom Core provides two primary methods of placing inanimate objects such as buildings using bot-objects or importing the content as an instance group. In the Ryzom Core stock continent you can see both versions of object placement - there are several outlying buildings in the "newbieland" village which are placed statically using an instance group and on the top of the hill where the three stock NPCs are lurking is a guard tower which is placed using the bot-object variation.

Bot Object Buildings

I don't intend on giving a thorough tutorial on constructing and placing buildings but placing a building using a bot object is fairly simple. You can look at how this is accomplished by referencing the guard tower.

1. Create your shape and ensure that it is in the media database (e.g. W:\database\Stuff...)
2. Clone the object_watch_tower.creature sheet and change the shape used.
3. Execute the build_gamedata pipeline to export the .shape file and update packed sheets.
4. Add a new NPC bot using the new creature sheet. Place appropriately.

I can illustrate these steps in a future post or tutorial but this is the essence of how to do this. 

Pros: Quickly and easily place inanimate objects on the landscape. Provides a dynamic means for modifying and moving these objects without needing to patch the client.

Cons: Consume an entity slot and must be directly tracked as an entity on the server side. All lighting and effects are performed dynamically. No complex scene objects such as instance groups are supported - meaning no portal/cluster support and no PACS triggers for teleportation, elevators or doors.

NPCs standing in front of the bot object guard tower in Ryzom Core.

Bot Objects are very useful if you want to quickly (and dramatically) alter terrain and the layout with minimal effort and little or no patching required on the client. You can use them to quickly alter an area for an event, for example, and then revert the changes back assuming all of the relevant media is already distributed to the client.

Static Buildings

Static buildings are the best way to build large areas of inanimate objects such as a city or town. Because all of the data necessary to display these on a landscape zone are already on the client the client has a much greater ability to display and cull the geometry. When using the bot object method you may notice a "popping" of buildings - this is because the server has to make decisions based on priority, number of entities visible and entity view distance to determine whether or not to inform the client of the existence of the bot object. If you wander around Silan on the official Ryzom game servers you will know what I'm talking about. Using a static building leaves all of these decisions up to the 3D engine and removes the server as a component.

Pros: Advanced functionality and no reliance on the server for visibility. No "popping" due to priority or viewing distance.

Cons: Hard coded to the landscape and requires a full regeneration through the build pipeline. Cannot be dynamically manipulated. Substantial setup required within the 3D modelling package, in the build pipeline and in World Editor.

A custom placed static building on a development shard.

Unlike the bot objects which just use the pipeline to run an export and simple shape optimization a static building will require the landscape for the continent to be completely regenerated. The pipeline will place the instance group representing the building onto its target zone and then run it through a series of lighting and shading passing and ultimately ends up "baking" the building onto the landscape. 

Since bot objects tend to be simple objects the engine will just "snap" them to the landscape when it spawns them using the same technique that it uses to snap characters to the landscape. Static buildings tend to be more complex and have more reliance on the shape and position relative to the landscape in order to provide walk-able collision areas for things like doors. This means that process is more substantial:

1. Assemble your building in a tool such as 3DSMAX.
2. Import the building into a landscape brick using the building xref tools.
3. Deform the landscape to accommodate the building.
4. Use the pipeline to export the landscape brick and zone information.
5. Copy the brick data generated above to the corresponding World Editor continent so that it is available.
6. In landscape mode place (or replace) the zone.
7. Run build_gamedata and update locations accordingly (e.g. data_shard, patch, client install, etc)

Ryzom Ring Crash Resolved

After an epic 6 month long battle in the Ryzom Core community to set up a Ring shard and build enough data to test and debug the Ring crash we have finally done it and the resulting fix was pretty anti-climactic. In the end we changed one whole line of code but the journey exposed us to the vast underbelly of the Lua Reflection code within Ryzom Core's client.

Some people will look at the fix and wonder why it took so long to get to that resolution. I covered some of the details above - there was no official open source Ring shard and we didn't have the data to set one up. So we had to painstakingly piece this information together. Bearing in mind that the Ryzom Core Ring shard still doesn't fully function because we're still piecing the data together. At least now we have a client that doesn't crash.

But debugging the Lua scripts has proven to be extremely difficult as once we get passed CLuaState::executeFile debugging information is essentially a blackhole. We had to harness in code to iterate through the Lua files to disocover what method call was crashing us. This was quite literally logging after each method call or variable assignment to a log file. We discovered that it was an assignment the retrieval of a ucstring member which didn't really help us since there was almost no activity on CI18N or in any of the GetUCString helpers. Lua IHM was essentially untainted.

After some complete luck we put a breakpoint in CLuaIHM::luaUIIndex and were able to step through this function to the actual failure. In this function we could discover which class, methods and members were involved by inspecting the reflected property. In this case there was a class that had been changed: CGroupTree::SNode. Down the road this has been sanitized to have the getter/setter methods for const-reference sanity. Lua has no binding for "const ucstring &" and thus panicked late in the process.

So the fix? Remove const-ness and the reference from the return value. We deleted 6 characters from a header file.  Behold the fix.

Ryzom API and WebIG Framework Now Open Source!

So pretty big news in the world of Ryzom Core. In order to greater enable one of our Summer of Code students to succeed Winch Gate has graciously provided the full source to the server side components of the Ryzom API and Ryzom's WebIG system.

So this is great news for people developing games using Ryzom Core but it is also pretty awesome news for Ryzom players with development skills. The Ryzom API that is available to players for development of external applications is pretty robust but doesn't provide a wealth of low-level access and does not embed into the game the same way WebIG does.

Now Ryzom players have the ability to create and contribute in-game applications!

About Ryzom API and WebIG

The Ryzom API has two main components - a server side website and client library. The server side component is what was just released. The Ryzom API allows third-party developers to develop their own applications using a simple ReST-style web service. The client API provides a PHP interface for web developers.

The Ryzom WebIG (Web In Game) system provides the basic framework for providing rapid functional development in Ryzom Core without the need to modify the client and distribute patches. The WebIG framework is a powerful way to add a very large amount of functionality very quickly. It also provides a dual purpose platform as most WebIG apps can also be accessed via the web. This allows game developers to minimize the amount of development needed for applications

• See the Ryzom API site for more information
• See the source code.

Configuration and Setup

The set up should be pretty straight forward. You will need to rename the config.php.default configuration files to config.php in their respective locations:

• code/web/app/config.php.default
• code/web/api/common/config.php.default
• code/web/api/server/config.php.default
• code/web/api/client/config.php.default

In the these files you will need to correctly set the RYAPI_URL and RYAPP_URL variables to the correct path, e.g. http://app.mygame.org/. In the API server configuration you will need to configure the RYAPI_NELDB_* variables to your nel and ring_open database. These are the same settings you would use when setting up the other shard configurations. Finally the RYAPI_WEBDB_* variables define the database host, user and password that will be used for application databases.

For example to the demo app app_test you'd create a new app_test database with a table called test with two columns: id and num_access. See this code for an example:

$db = ryDB::getInstance(APP_NAME);
$db->setDbDefs('test', array('id' => SQL_DEF_INT, 'num_access' => SQL_DEF_INT));
$db->update('test', array('num_access' => ++$num_access['num_access']), array('id' => $user['id']));

Getting Started

There's already a ton of information on the Ryzom API site for using the API and a number of great example applications created by Ryzom players available on places such as Github. Check out the contest submissions, there's a lot of great code and great ideas there!

Getting started writing a new WebIG app is pretty simple too. You'll need to copy app_test and then add your new app_whatever to code/web/app/lang.php and code/web/app/index.php so that the WebIG framework knows about your application. If your application uses a database you will need to create the new database, using your app name, using the host/user/pass specified in the RYAPI_WEBDB_* configuration variables.

Feel free to join us on irc.freenode.net in the channel #ryzom for more information or if you need help!

Tutorial: Creating a Guild Master

A lot of functionality in Ryzom Core relies on guilds existing. In the default shard information that is provided with Ryzom Core there is no NPC guild master. Creating a guild master is actually a really simple exercise. In this little tutorial I'll show you a couple quick tricks for development and troubleshooting and then jump right into the meat of creating a guild master and then founding a guild in the game.

Development Tricks

There are a couple quick and dirty tricks I used to make sure I had the necessary access and money to test the guild master out. The first one is to grant your player DEV privileges.

There are two main commands you will use to grant yourself DEV privileges. You can always access the data_shard folder and decipher your player ID from your PDR file name but it is much easier if you log into the shard and use the displayPlayers command. The player ID is pretty evident if you look at the example below. You then use the setPriv command to grant yourself privileges. The DEV privilege is the main one you need for this exercise: setPriv <uid> <priv>

displayPlayers
INF b71126d0 94.136.70.53/EGS-136 : Executing command : 'displayPlayers'
INF b71126d0 94.136.70.53/EGS-136 : Player: 1 Name: Karlin(Open) ID: (0x0000000010:00:00:87) FE: 135 Sheet:fyros.race_stats - 21 Priv: '' Pos: 10305,-11722,5 Session: 302
setPriv 1 :DEV:
INF b71126d0 94.136.70.53/EGS-136 : Executing command : 'setPriv 1 :DEV:'
INF b71126d0 94.136.70.53/EGS-136 : New priv for player 1 is ':DEV:'
displayPlayers
INF b71126d0 94.136.70.53/EGS-136 : Player: 1 Name: Karlin(Open) ID: (0x0000000010:00:00:87) FE: 135 Sheet:fyros.race_stats - 21 Priv: ':DEV:' Pos: 10305,-11722,5 Session: 302

Another one that is useful is the /a command from within the client. In this case you will need money to found the guild so use the /a command to execute Money like this:

/a Money 1000000

There are a slew of handy admin commands available in the client but that is a topic for another article.

Creating the Guild Master

You will have to create an NPC in World Editor that will be responsible for handing out guild creation requests. If you look at your shop_categories.cfg in data_shard you'll note that one of the available categories is "guild_creator." This is the shop category that enables an NPC to found guild for a player.

To place this NPC:

1. Open up newbieland.worldedit in World Editor
2. Add or expand the urban_newbieland.primitive
3. Expand the rangers_starting_city npc_manager
4. Expand the important_npcs npc_zone
5. Add a new npc_group, accept the default parameters and set the name to guild_masters
6. Under guild_masters add a new npc_bot
    
7. Set the name to nbland_guild_master$fct_nb_guildmaster$
8. Add two chat_parameters lines:
1. shop:guild_creator
2. menu: MENU_WHOAMI WHOAMI_GUILDMASTER
9. Set the sheet_client to company_of_the_drill_loge_master_z_h_b1. Note that you can use any valid existing .creature sheet here. This just happens to be the one that is used for the existing NPCs on Ryzom Core's Newbieland.
   
10. Move the Prim Point representing your NPC to where you want it located on the map.
11. Save your changes.
12. Restart your shard.

Bear in mind that we haven't discussed the menu options so nothing will be translated when interacting with the NPC (the whoami menu.)

Optionally you can customize the look of the NPC. You might want to do this since we're going to use the same creature sheet as the other default Newbieland NPCs. You do this by setting the color of the five equipment slots. If you look at the screenshot above you will see that we set each equipment slot to a number. These numbers (0 through 8) denote a color:

Color	Value
Red	0
Orange	1
Green	2
Turquoise	3
Blue	4
Purple	5
White	6
Black	7

Creating the Guild

Actually creating the guild is the easiest part of the process. Assuming you have enough money (see Development Tricks above) all you need to do is locate your NPC and choose the Create Guild action and begin entering the details.

Creating the guild. Give a name and design your flag.

Viewing your guild information.

Next Steps...

This is only the very basic of guild-based configuration. There are other NPC roles and topics to investigate such as guild_rolemasters, guild_caretakers and charges. Maybe next you'll drop a community building on your map and set up a caretaker and rolemaster in order to buy and customize guild halls. Maybe you'll create a guild-based mission.

Hope this helps get you started in guilds!