squelch mod - need a code review

NT

Quick notes: 

So I'm just toying and testing with the full code atm.  Decided to add another command so that's its easier to squlech in game.  Added /s <playername>.  This works fine.  Going to include that functionality and provide a quick writeup explaining how squelch works as I don't think many/any use it.  The /s change required little to no work - tests ok.

tested the mod out with doggu.  All functionality seems to work as intended.  Its a UI only mod (so no one else needs to have it enabled).  It has no impact on the lobby (expected) and only impacts in game play.  By adding doggu to the list of ignored players in the lua, I was able to have him automatically squelched when the game started.  Then, by using the /s doggu command, I was able to unsquelch him. 

As far as interesting things, it would be cool if i could figure out how to pass a command through chat that would return a number associated with a player and then mute based on that... something like /list

and that returns

pacov - 1

blah - 2

then i type /s 2 and blah gets muted. 

Just some quick thoughts.  Methinks I'm done playing with this atm, though. 

or perhaps figure out a way to squelch all and unsquelch all.  Not generally what you'd want to do, but it could be useful to just quickly type /sall or /uall. 

 

Going to sit on this for a few days and then just add it in as is as a standalone mod and add to enhanced ui.  Any feedback appreciated on the code mess.  TIA

Like I said in your PM, it should be easy enough to modify the squelch system to save to and load from preferences.  I'll take another look at the preferences system, and see what I can come up with.

Until then, I'm willing to help, but I'd really prefer to help you learn to use non-destructive hooking first, as it's very advantageous and fairly simple.  I'd much rather fix and explain a failed attempt at a hook than have to re-write all of someone else's work for them - I'm sure you can understand?

Got some time to work in this last night, and a bit this morning.  I could only test it with bots, which have very different rules regarding nicknames, chat, etc and I had to modify a lot of conditions to make the bot squelching and list management work.  So, I don't know if it works with actual human players, but this version has all of the right conditions in, so it should.

If it isn't obvious from the code or the comments, this does a whole lot more than what you asked for, but it wasn't too difficult to add the extra framework/features.  Type /? or /help in the chat for a list of current commands, and see the comments for how to add more.

Features so far:
- Slash commands are saved to the up/down arrow command buffer, same as chat messages
- Issued commands pop up the chat window with normal hide delay so you can see the result of what you entered
- Better display of non-chat text, including window size adjustment, selective wrapping, etc
- New command infrastructure that makes it easy to add new commands and supports help text and multiple aliases for each command
- Commands for adjusting chat font size and window auto-hide time added, both save to the current profile
- Player names you ignore are saved to a persistent ignore list in preferences.  Names in the list are auto-ignored on game start (if present) and the chat window pops up with notifications for any ignored players in the current game, so you don't forget.  This is done on a 5-second timer after chat.lua loads, so slower computers may not get to see this with default chat timeout.
- Limited ignore list management: you can view the whole list including offline players (with players in the current game at the top, denoted by a star), but for now I kept in the limitation to only add/remove player names that are actually in the current game, mostly to prevent mistakes with mistyping names.  I'll add a separate command to add/remove offline players if anyone cares, but you can already do that by (carefully) editing the IgnoreList table it creates in your game.prefs.
- Player index list, with support for ignoring based on index (/pl for the list, /i # to ignore)

I'll probably release this as a standalone mod myself, but I need it tested first - and of course you're welcome to include the finished version in the enhanced UI package.

http://pastebin.com/iYxggZpH

Miri - 1st, I'd like to learn everything I can about how to mod in a nondestructive fashion.  I know enough to be able to reverse engineer the code a bit and figure out what's happening, but there are quite a few holes in my logic here and there. 

So just to recap what I have here:  I copied a mod that chirmaya created that fixed an old issue with the squelch/ignore system.  That mod isn't needed at all as the issue was resolved in a later DG patch. I'm guessing I could have started with the original chat.lua file, but I started using chirmaya's version anyway.  Then, I modified the code so that you could explicitly indicate users you want to squelch on a regular basis by editing the lua.  Then I added a change to make it easier to squelch so that instead of type /squelch (or /ignore) you can just type /s + playername.  That's just a minor enhancement that I thought would help people quickly squelch in game.  Anyway, that's the goal and that all works perfectly and tests out fine with how I coded things. 

That said, what I want is to code it proper - only I'm not sure how and I don't think I fully comprehend non-destructive modding.  I don't know precisely what I can exclude and what I need to include - and that's where I'm looking for some assistance.  Any explanations that you can provide to fill in the blanks that I don't get will make things much easier for me to understand (and will help me to learn how to do non-destructive hooking).

Can you perhaps explain how things work a little more?  For instance, without a mod enabled, the game would just check the normal lua location in dgdata.zip, right?  But if you enable a mod, it will check the dgdata.zip 1st, then looks at the modded lua (as long as its named appropriately and in the corresponding folder.  Am I right so far?  When you referred to destructive hooking, that's when I overwrite existing functions etc in my modded lua?  Or what precisely.  Anything you can explain along those lines will help.

Every time the engine executes a file from dgdata.zip, it looks in each mod's /hook folder for a file with a corresponding path and name, appends it to the original and executes it as one chunk.  So anything that's in the original file does not need to be included in a hook, as it's already still there.  The mod hooks of the file just add onto the end of the same file, and everything in the original is accessible, including any local variables declared in the main block of the file (outside of any functions, loops, conditional blocks, etc).

This is also why if you have a syntax error in a hooked file, the entire original fails to parse, and also why it only lists the path of the original file and only one line number - it's joining them together before it even tries to parse the code contained therein.  That's also why the line number represents the entire original file plus the number of lines in the hooked file prior to the error (e.g. if the original file is 200 lines, and the log error says line 220, that's likely line 20 of the first hook of that file).

So, like I've said before, always start your hooks from a blank file.  Never copy an existing file.  You want to have the original file open for reference and copy-pasting bits of code, but you only want to hook or override what you absolutely need to.

 

Everything else you can pretty much figure out by comparing original code to existing mod code that hooks it.  Learning to hook functions and classes is pretty simple - it's just a matter of saving a reference to the current version, re-defining it, and calling the original (adding your code in either before or after calling the original, as appropriate).

Sometimes you have to destructively override a function.  It can almost always be avoided when the original function was made with hooking in mind, but obviously GPG was strapped for time, and many of them are not.  With the exception of some inline texture file paths defined as local variables, most UI code can be hooked non-destructively without much effort.

In addition to the xp bar hook that I just did (which tells you everything you need to know about hooking functions, including functions defined within tables/objects by other functions), the UberFix is a good place to start, as I've commented just about everything in it including why I've overridden certain functions.

ah... ok. 

So, what you refer to as destructive is if I completely overwrite something in a mod that exists in the dgdata.zip?  eg if a fuction called bob exists in the dgdata.zip and I reprogram that function in the modded lua (eg I reprogram the function bob by just directly recoding it and calling it bob). then that's destructive?  Am I following you?

And you are saying that if there is a function called bob in dgdata.zip and I need to modify that, what I want to do is create my mod lua, call the function and save it as something else... It think I'm missing some things here.  Anyway, I'll review that xp bar hook today after work.  If you can think of anything else for me to chew on, I'm all ears.  Set me straight, miri!  And thanks.

I guess I'll throw out a few more questions.  Let's say there is a function that I need changed.  I'm just going to copy paste info from the chat.lua.

Let's say (and it probably is) that the code above is exactly what is in the dgdata.zip.  Let's say that my one goal is to create a mod so that the line bg.historyBackMid:Hide() is removed.  What would be the appropriate way to code that?

 

More or less, yes.  If, for example, your hook is a copy of an original file with a few changes, it's 100% incompatible with any other mod that changes anything else in that file, because everything will be re-defined and the other mod's changes will be overridden with the 'original' code that you're duplicating.  It's also incompatible with any hypothetical future Demigod patch that changes that file, however unlikely that is to happen at this point.

 

You can't directly erase functionality from an existing function without completely overriding it.  However, in most cases, it's possible to just change something back.  In this case, you would assign a local variable the current version of that function, re-define the function, run that saved copy, and then do a Show() on whatever you didn't want hidden afterwards.  Just like the XP bar hook does with both the hidden controls and the text position.

As I just mentioned, the only time you're out of luck when it comes to un-doing something is when it's declared locally and used within the same chunk of code, with no external or post-run opportunities to change it.  This is, as far as I'm aware, how most e.g. UI background textures are assigned.  Some control/bitmap types might allow a new SetTexture call afterwards, but in my experience some don't.  In those cases, you have to override the function with an altered copy of the original (but even then only that function - nothing else in the file).

 

Anyway, if you get a chance, test out that chat.lua hook in an actual multiplayer game, and make sure the ignore commands (particularly the auto-ignore and the ignore-by-index) work on human players.

ah - ok.  So the bottom line is learning to take exactly what you need and only what you need.  I think I get the logic.  There are still some bits I'm missing though, but getting close to a better understanding.

When you say overriding that, that's when I'd name a function the exact same thing as its called in the dgdata.zip and program it "again" in the lua?  I have that right?

I think I see what you are saying here... so you'd just leave the original function alone and create a new one that forced it visible?   That right?

I'm not exactly sure what you mean.  I tested the full mod (eg all of the code - sloppy as it is) in MP and it worked perfectly.  Are you saying you just want me to test a small section of it in MP?  Anyway, sorry to overdo the probably obvious questions, but I'm trying to get a good understanding that should help the silly questions die a bit.

 edit - I just noticed you updated  (or I completely missed reply #6).  I'll look into that.  Thanks!

quick question (and like all my questions... brilliant :O) - I notice at the start of your code you pull local prefs.  I don't have access to that file from here - why are you importing this in your mod?

Right.  Technically a hook is also an override, in that you're hijacking the name of the original function, the difference being that you're saving and calling the existing version of that function.

 

If by 'create a new one' you mean hook the original function, then yes.  But you're not exactly leaving the original alone, you're saving it to another variable and co-opting its name so that whenever it would be called, your code runs before or after the existing code in the copy of the function you saved (which has to be explicitly called in your re-defined version of the function).  Again, look at the XP bar hook - this is the first thing done in the file, and I think I commented it pretty well.

ok i get it.  thx.

I'm reading xp.lua again - and yes - you did appear to comment it well :P  thx

question about the mod you are working on (and yes, I can test it out for you in MP - np) - with how you've coded it, does simply adding someone to the ignore list in game cause that person to persist over to the next game?  My method required editing the lua itself.  Does yours require that as well or did you come up with a way where you just ignore in game and it persists?

And another question- how do know what options are available for a function.  For instance, in the xp mod, you use OnHeroChange(unit) - and also function create(parent) - how do you know what you can use?  I'm referring to whatever appears between ( ).  Is this defined somewhere?  That would fill in a big blank in my understanding.  Thx.

and one other thought about the mod you are working on.  Is there any way you can create some sort of toggle that might capture the in game chat to a txt file?  Even without a toggle, something like that could be fun.

abt to do some testing.

-Testing done - I'm thinking I might bundle up a beta version of this so we can get some feedback from more folks.   I tested /?, /s, /pl, then squelching by player list number.  Also tested unsquelching - worked fine. 

Played to games with darkliath.  Muted her in game 1.  Hit end game and hosted another.  Message displayed indicating that she was muted.  Tested and she could hear me - i could not hear her.  So, the ignorelist seems to be propagating perfectly.  Nice work. 

Linky to exe: http://www.box.net/shared/lr2k101hj90fax35lugj

I did create an UID in case you want to keep using that for the mod.  Let me know if you need further testing, if you are planning on a new version, etc.  If this is what you are sticking with, please let me know that as well and I'll integrate it into the enhanced ui mod.  Thanks!

Oh - and here's the inno script in case you want full control for your final:

Thanks for testing it.  Good to hear that it works with players - it took jumping through a lot of hoops to test it with bots, and obviously in a normal game I don't want bots to show up on the player list nor be ignorable.

I'm not sure how much I'll expand it at this point, I guess it depends on how badly people want built-in offline list addition/removal, or what other similar features I or others can think of - chat size and timeout were obvious, because I found both to be really, really annoying at default while testing the mod myself. 
The chat size still kind of needs an adjustment to the line number calculation-- there are 10 history lines at font size 18, but if you make it smaller, there are more than 10 and the auto-width adjustment only adjusts to the last 10 lines which occasionally makes the window narrower than the earliest two or three lines of visible text.

 

They're defined right there, in the function definition itself.  When you define a function, you also define the names of its parameters.  I could call them 'bleeg' and 'flarn' if I wanted to, and they'll still represent the first two parameters passed to any call of that function, and it's the number of them that's important, not their names.  This:

..is perfectly valid, and neither the previous version of OnHeroChange nor any other mods that hook my version of the function know or care what I named the parameter variable, only its contents.  I could even add an extra parameter, although in this case, that would do nothing since the function is only being called with one parameter.  Lua is really flexible when it comes to things like this.
You can remove parameters too, which is essentially what happens when OnHeroChange is called in observer mode or with a dead demigod (the parameter passed to it, normally the user unit object for that demigod, is nil, or non-existent-- which is what caused problems for the original mod), but there's pretty much never actually a reason to remove parameters from the function definition itself, especially a function that multiple mods may hook (as that would break all mods that rely on those parameters).

As mentioned, the number of parameters passed to the function in any/all of its calls determine how many it needs in its definition.  Or, more accurately, the reverse, but when you're hooking an existing function, that's how you know for certain what's being passed to it and how many parameters it uses.  In the case of OnHeroChange, it's initially confusing, because the function is never called directly in HUD_xp.lua.  It's added as a callback function via /lua/ui/game/InGameUI.lua, and called by SetFocusArmyHero on line 125 of that file with one parameter - the unit passed to that function by UpdateForNewArmy at line 27, which you can see getting (or failing to get) a handle to the hero unit.

 

I'm not sure.  The game only allows lua to write to the preferences file (which has limitations) and the log.  I could make a UI-side mod that outputs all chat messages to the log fairly easily, and gives them a unique tag so that they're easy to search/filter for, but you'd still have to run with the log enabled, and find some program to pick them out of all the other spam.

In fact, it's so easy, it took about 3 minutes: http://pastebin.com/bLnFAHGh

Not tested, but it's pretty simple.  I just hooked ReceiveChat, aped the first part of its sender formatting/localization, prepend [CHAT] and/or *ignored* to the message, and dump it to the log.  No on/off switch, but it's probably not something most people will use / know how to use anyway, so it's best in a standalone mini-mod.  To be clear, this only logs chat received in the UI, and has no more access to enemy team chat than the normal UI.

is there a sample of any output you wouldn't mind posting?  I'm guessing its just a bunch of stuff to wade through.  Curious.

ah nevermind... the words not tested imply you don't have a log

I'll look at this later.  Thanks for all your help!

The average log for a full game is about 3000-6000 lines.  So without a tool to pull out lines starting with [CHAT], you're limited to using the log window (/showlog), filtering by that string, and copy-pasting.

Oh, and the game will erase and re-start the log file every time it starts up (not every game, just every app start).  So if you really want to save the chat messages (or anything else in a log), you need to do it right after you exit.

ok - i'll prob take a look.  If its not just a chat file, then I'm not sure I'm interested... but still... if we add it on, it probably won't hurt.

Oh - and if creating a list works fine in game (it does), then I don't think we need an offline component.  I didn't really want folks to have to edit a lua file in my version of the squelch mod, but it was all I knew how to do.  Yours works better and I think removes that need. 

So - let's let it sit for 2 days before we finalize anything.  That work for you?  Do you want to release a finalized version along with a new post/changelog/blahblah or do you want me to take care of that, bundle it up, create the post, etc?  Obviously all credit to you on this mod and thanks for taking the time.  Whatever you want - I just want to finalize so I can add this to the enhanced ui and we'll call it a day. 

Let it sit for a few days at least.  It's right at the top of the forum, and people who are interested can certainly try it out for now.  I wrote it in a few hours and probably didn't test every angle, and I'm not sure whether or not I want to add to it yet.

righto.