LABELS how-to

[Lauriel]

It has come to my attention that the use of labels is a "best practice" that is often overlooked.  Using labels makes it much easier for other modders to work with or around your content.

The suggested format has been put forward:

<two letter modder prefix>-<tp2 name>-<descriptive label>

like: LABEL "#L-TRANSITIONS-SNARK"

This suggestion has been changed to be <two letter modder prefix>-<something that makes it unique-point of origin is not a bad idea>-<descriptive label> AND if the component is shared with another mod, it should retain its original label.  The point is to make it globally unique and static.

To use a label, just put something like this in your TP2 file:

///////////////////////////////////////////
// ADD SOME SNARK TO STUFFY SOD DIALOGUE //
///////////////////////////////////////////
BEGIN @5   // MOD 10
DESIGNATED 10
LABEL "#L-SOD-SNARK"
REQUIRE_PREDICATE !(MOD_IS_INSTALLED ~transitions.tp2~ (ID_OF_LABEL "transitions.tp2" "#L-SOD-SNARK")) @3
INCLUDE ~mynewmod/components/snark.tpa~
LAF snark END

 

Edited September 4, 2020 by Lauriel

[DavidW]

I don't think labels need a standard format. They're mod-relative. If someone checked your LABEL, they'd do it like this:

ACTION_IF
	MOD_IS_INSTALLED "transitions.tp2" ID_OF_LABEL "transitions.tp2" "#L-TRANSITIONS-SNARK"
BEGIN
...
END

So the modder prefix and the tp2 name are redundant - unless there is another mod present with the same tp2 name, but then you've probably got bigger problems. (There is a case for putting your modder prefix into the tp2 name for that reason.)

[Lauriel]

9 minutes ago, DavidW said:

I don't think labels need a standard format. They're mod-relative. If someone checked your LABEL, they'd do it like this:

ACTION_IF
	MOD_IS_INSTALLED "transitions.tp2" ID_OF_LABEL "transitions.tp2" "#L-TRANSITIONS-SNARK"
BEGIN
...
END

So the modder prefix and the tp2 name are redundant - unless there is another mod present with the same tp2 name, but then you've probably got bigger problems. (There is a case for putting your modder prefix into the tp2 name for that reason.)

It has to do with Project Infinity and sharing components across mods.  So if someone likes my snark (heh) they can put it into their mod and still keep the blame on me.  Like "#L-IMINNOCENTDONTBLAMEMEMOD-SNARK" and if I contribute to someone else's mod, I'd like to have it have my prefix even though it's in their mod.

EDIT: I already have multiple prefixes in my mod because I snagged code from another source and would like folks to know who wrote it.

Edited September 3, 2020 by Lauriel

[DavidW]

That's reasonable enough - my point is just that I don't think there's a 'best-practice' reason to do so. 

[Lauriel]

35 minutes ago, DavidW said:

That's reasonable enough - my point is just that I don't think there's a 'best-practice' reason to do so. 

You don't think using labels is a best practice?  Seriously?  Well, I'll not argue the point with you, but I'm rather surprised.

Edited September 4, 2020 by Lauriel

[DavidW]

I think there's a reasonable best-practice case for using LABELs. (Indeed, LABEL is my idea - I originally suggested it to Wisp's predecessor as WEIDU maintainer, in the long ago of the world). Basically that it insulates against changing component number. It's somewhat complicated by the fact that WEIDU 246 has some runtime overhead with LABEL that's a bit painful in something as complicated as SCS, which is why I don't use it myself. (I coded it a couple of years ago and then reverted it when the runtime overhead got too annoying.) I believe WEIDU 247 may improve on this, in which case I might rethink.

I don't think there's a best-practice argument why the naming format for LABEL needs to take any particular form. Any WEIDU-legal check for a label is a check for an ordered pair <tp2 name, label_name>, so label_name is, by design, inside a namespace local to your mod. And the reason for prefixes is to avoid naming conflicts within a shared namespace. So label_name doesn't need modder prefixes. 

 

[Lauriel]

56 minutes ago, DavidW said:

I don't think there's a best-practice argument why the naming format for LABEL

Only if you don't care about taking full advantage of Project Infinity, which is what it would useful for.  If you don't want to support that project within your mods, that's up to you.

[DavidW]

Do you mean that Project Infinity is also using LABEL as metadata? Do you have a link to documentation? - I'm not sure how that would be supposed to work, and insofar as I can guess, I still can't see how a modder/tp2 prefix inside the LABEL would be helpful. (After all, PI could just add the tp2 explicitly if it wanted to - it's lifting the data from the tp2 file, after all.)

[Lauriel]

6 minutes ago, DavidW said:

Do you mean that Project Infinity is also using LABEL as metadata? Do you have a link to documentation?

@AL|ENdo you have documentation for this?

 

6 minutes ago, DavidW said:

After all, PI could just add the tp2 explicitly if it wanted to - it's lifting the data from the tp2 file, after all.

I did ask about this.  But you'll need to ask him yourself.

[AL|EN]

@DavidWCamDawg come with the idea of having modders prefix as part of the LABEL so they can be unique globally. It would be very helpful because the usage context of the LABEL in PI is free from weidu limitation - labels are not bound to tp2. It's like solving two problems at once by using well established and accepted 'modders best practices'. So I support this idea.

Even without modder prefixes, current usage of the LABEL across multiple mods and authors indicate that they are globally unique so I don't see any reason why they shouldn't be treat that way.

There is no documentation yet because I don't know yet what are opinion about this. But for sure, crafting labels with modder prefix is the best way to go.

[DavidW]

I’m afraid I still don’t understand this. Even if you’re getting LABEL to double as metadata (which I’m not convinced is a good idea, given that it ties metadata to something that also has a functional role in WEIDU, but I can see the elegance) then you can perfectly well get PI to treat the metadata as the concatenation of tp2 name and LABEL entry. Why try to get global uniqueness through asking people to do it voluntarily, when it’s in your power to do it automatically?

[AL|EN]

But using tp2 as part of the ID is fine until one modder decide to transfer/donate his components into another mod tp2. Knowing that and being a witness of broken players saved mod lists/mod compilations etc I can't turn my eyes away. How do you feel about the requirement of globally unique labels (which can be achieved unconsciously during their creation) vs the potential benefits?

[AL|EN]

The only valid alternative for using prefix as part of the labels is adding 'special magic sting' at the end of the label itself:

LABEL "CD_TWEAKS_REMOVE_HELMET_ANIMATIONS_01AN4Z07BYMQJ"

or using second label with only 'special magic sting'

LABEL "01AN4Z07BYMQJ"

The advantage is that it's a no-brain operation: you generate 1000 of them, putting into every component and you don't have to worry about anything as long as you don't change it for already established code/component or use for another code/component.

It 100% globally unique and at the same time, PI can validate/detect it. The downside is that it looks ugly. And  'special magic sting' needs to be generated outside of weidu...

Edited September 4, 2020 by AL|EN

[CamDawg]

For me it's just that we already have a tool to avoid namespace collision--the modder prefixes--so this is a natural fit for labels. So even though it's redundant, I'd use something like cd_tweaks_cosmetic_remove_helmet_animations or somesuch for Tweaks labels.

 

[DavidW]

OK: I think I'm being confused by Lauriel's original post, which suggests that the mod tp2 name ought to be part of the LABEL. That was the bit I didn't understand, given that the tp2 name is inferrable anyway. If the point is just that you want global uniqueness and so a modder prefix, that makes more sense.

Is this correct:

• PI is using LABEL as metadata
• PI's syntax is not restricted as WEIDU's is to checking LABELs only of a particular mod, so LABELs can follow a component even as it migrates between mods (and should not be changed when a component migrates).
• For that reason, it's helpful for LABELs to be globally unique. (And use of modder prefix is the standard way to do it.)
• In fact, it would be helpful if people use globally unique LABELs (hence modder prefixes) even for components that have no prospect of being migrated (e.g., SCS's 'Smarter Mages') because otherwise they might trespass on some completely different mod's LABEL namespace and cause PI to get confused.
• For modders with more than one mod, it would be helpful if they can make sure that their own LABELs are globally unique, and that they don't use the same LABEL in two mods. Modder prefix alone won't do that; including the tp2 name is one way to do it.
• BUT if you include the tp2 name in a component LABEL you should absolutely leave it unchanged even if you then migrate the component into a different tp2. 

OK, I think that's a reasonable ask. (It's mostly moot for me for the moment because v246 slowdown means I can't use LABELs with SCS.)