Bulle
01-19-2008, 02:47 AM
Full function-hooks for rules (implemented)
Hello guys,
I have been fiddling with EQEmu for a couple weeks, and played EQ for several years. And as many world builders I have embarked on a quest of my own : create a custom server, with my own ideas of what the rules should be.
It obviously means customizing the EQEmu emulator code. Which inevitably leads to code merges hair-pulling down the road as soon as you touch code written by the rest of the community who tries both to implement a sane game mechanic and the pristine EQ rules.
I would like to minimize the code merges I will need to make n the future. As much as I would like to get the bug fixes, improved game mechanics etc, I would also like to keep my code for custom rules like evaluating the fizzle chance, hit probability, damage etc. In a way I would like to benefit from advances in "mechanics", while keeping my own "rules".
Immediately the rules mechanism in EQEmu came to mind. Except they are quite limited, as they only allow for tweaking a few numeric values during the processing. You really need more than that when you develop a custom world (don't you?).
May be then it was my professional background calling to me, but I saw only one solution : allow developers to separate the game/server mechanic from the rules. The usual tool : function hooks.
Let's take an example : the zone server needs to execute the casting of a spell by a player. It means graying its spell gems bar, waiting until the cast time is over, computing the channeling chance if an interrupt can occur, check whether a fizzle happened, then finally cast the spell and apply its effects. If you look at the fizzle computation, the fizzle chance computation is right inside the rest of the spell casting code. Wouldn't it be nice that the casting code simply called a function computing the fizzle chance (a percentage), and that this function could be defined by the rule system ?
I thought it would be nice to have this, so I implemented it. It was not a huge indertaking as most of the rules code was there, it just needed to handle one more case : we had integer, real and boolean rules, now we can have function hooks.
Here is how it works :
- the emulator code chooses to call a function hook at a certain point. This has to be coded in by the emulator developer, as part of the processing. At this point the parameters passed to the hook (character level, skill score etc) are decided, as is the result the emulator code will accept (say, the hook can return a float, which is the fizzle chance)
- the world builder has written a function matching the function signature for the hook, and has compiled it in a shared library (Windows DLL, Unix .so). The library is stored at the same place as the other server executables.
- the world builder has created the appropriate rule in its database, with a value like "library:function", library being the shared library name, function being the hook function the server must call
- the emulator code will call the rules sub-system, who will load the dynamic library and provide the hook(ed) function pointer to the emulator code
- the emulator code calls the function that implements the rule
If the world builder did not define the rule, the default hook is called. It contains the exact code the emulator server currently imbeds in its processing (that is, this code is moved from its current place to a different file in "common", and is the default implementation).
I could successfully test the implementation of this mechanic on Windows and Gentoo Linux. On Windows it relies on the regular LoadLibrary and GetProcAddress APIs. On Linux it uses the functions dlopen and dlsym of library libdl, which should be common on most Linux installations nowadays (I think it originates from FreeBSD, but I could be wrong). For other platforms I have no way to write/test the code so someone would have to take over. The shared library loading itself is pretty much isolated in one "case" branch in rulesys.cpp, so it's only a few lines of code to adapt.
There is one limitation of the implementation, due to how the rules system is implemented : you cannot dynamically save the hook setting to the database. The reason is that the hook is a function pointer, whereas in the database the library name and the function names are stored. This information is not avaiable in the Save function. I can live with that, but someone interested could probably add this functionality ot the rules system.
Last but not least, here is the code to make all this work. I hope it ends up in the official emulator in the end, it would ease my task :) And, given some time to replace hard-wiring rules into the code by well-thought function hooks, it could make the life of custom world builders easier.
I wanted to add a ZIP file to this post with the CVS DIFF file and the two new files, but it seems I do not ave the permissions. So you will have to suffer the inclusion of the files contents directly in the post ! And as it is too big to fit in one post, you will even get several !
The two files are a header file and an implementation file for the default rules implementation. They go to the "common" directory. Most of the contents are comments.
Hello guys,
I have been fiddling with EQEmu for a couple weeks, and played EQ for several years. And as many world builders I have embarked on a quest of my own : create a custom server, with my own ideas of what the rules should be.
It obviously means customizing the EQEmu emulator code. Which inevitably leads to code merges hair-pulling down the road as soon as you touch code written by the rest of the community who tries both to implement a sane game mechanic and the pristine EQ rules.
I would like to minimize the code merges I will need to make n the future. As much as I would like to get the bug fixes, improved game mechanics etc, I would also like to keep my code for custom rules like evaluating the fizzle chance, hit probability, damage etc. In a way I would like to benefit from advances in "mechanics", while keeping my own "rules".
Immediately the rules mechanism in EQEmu came to mind. Except they are quite limited, as they only allow for tweaking a few numeric values during the processing. You really need more than that when you develop a custom world (don't you?).
May be then it was my professional background calling to me, but I saw only one solution : allow developers to separate the game/server mechanic from the rules. The usual tool : function hooks.
Let's take an example : the zone server needs to execute the casting of a spell by a player. It means graying its spell gems bar, waiting until the cast time is over, computing the channeling chance if an interrupt can occur, check whether a fizzle happened, then finally cast the spell and apply its effects. If you look at the fizzle computation, the fizzle chance computation is right inside the rest of the spell casting code. Wouldn't it be nice that the casting code simply called a function computing the fizzle chance (a percentage), and that this function could be defined by the rule system ?
I thought it would be nice to have this, so I implemented it. It was not a huge indertaking as most of the rules code was there, it just needed to handle one more case : we had integer, real and boolean rules, now we can have function hooks.
Here is how it works :
- the emulator code chooses to call a function hook at a certain point. This has to be coded in by the emulator developer, as part of the processing. At this point the parameters passed to the hook (character level, skill score etc) are decided, as is the result the emulator code will accept (say, the hook can return a float, which is the fizzle chance)
- the world builder has written a function matching the function signature for the hook, and has compiled it in a shared library (Windows DLL, Unix .so). The library is stored at the same place as the other server executables.
- the world builder has created the appropriate rule in its database, with a value like "library:function", library being the shared library name, function being the hook function the server must call
- the emulator code will call the rules sub-system, who will load the dynamic library and provide the hook(ed) function pointer to the emulator code
- the emulator code calls the function that implements the rule
If the world builder did not define the rule, the default hook is called. It contains the exact code the emulator server currently imbeds in its processing (that is, this code is moved from its current place to a different file in "common", and is the default implementation).
I could successfully test the implementation of this mechanic on Windows and Gentoo Linux. On Windows it relies on the regular LoadLibrary and GetProcAddress APIs. On Linux it uses the functions dlopen and dlsym of library libdl, which should be common on most Linux installations nowadays (I think it originates from FreeBSD, but I could be wrong). For other platforms I have no way to write/test the code so someone would have to take over. The shared library loading itself is pretty much isolated in one "case" branch in rulesys.cpp, so it's only a few lines of code to adapt.
There is one limitation of the implementation, due to how the rules system is implemented : you cannot dynamically save the hook setting to the database. The reason is that the hook is a function pointer, whereas in the database the library name and the function names are stored. This information is not avaiable in the Save function. I can live with that, but someone interested could probably add this functionality ot the rules system.
Last but not least, here is the code to make all this work. I hope it ends up in the official emulator in the end, it would ease my task :) And, given some time to replace hard-wiring rules into the code by well-thought function hooks, it could make the life of custom world builders easier.
I wanted to add a ZIP file to this post with the CVS DIFF file and the two new files, but it seems I do not ave the permissions. So you will have to suffer the inclusion of the files contents directly in the post ! And as it is too big to fit in one post, you will even get several !
The two files are a header file and an implementation file for the default rules implementation. They go to the "common" directory. Most of the contents are comments.