Feature #1555

Explicitly define callbacks

Added by Hirundo almost 4 years ago. Updated about 3 years ago.

Status:ClosedStart date:
Priority:LowDue date:
Assignee:-% Done:

100%

Category:-
Target version:0.2.0

Description

I suggest to define both graphics and callbacks explicitly in the graphics block. This saves the user from having to fiddle with the callback ID and allows us to abstract e.g. CB 36 in a somewhat nice manner. I think it's best to do this before 0.1.0, to avoid people having to rewrite parts of their code later.
Example code:

item (...) {
    ...
    graphics {
        PASS: foo; //gfx for passengers
        MAIL: bar; //gfx for mail
        default: foobar; //default gfx
        purchase: purch_gfx: //gfx for purchase menu
        change_load_amount: switch_load_amout; //load amount callback
        change_running_cost: switch_running_cost; //switch for CB 36 -> running cost.
        purchase_running_cost: switch_running_cost_buymenu; //switch for CB 36 -> running cost while in the purchase list.
    }
}

Everything should be in one block, since we get big problems if the user conditionally skips certain sections of the graphics definition. We should also set the callback_flags property automagically so the user doesn't have to.

Depending on the circumstances there are two possible implementations. The first is to let the action3 chain to a single action2 that switches depending on CB id, and for CB00 (graphics) do a check on e.g. vehicle var 47 afterwards. The other is to do graphics selection in action3 and select the callback afterwards, using a separate switch for each cargo. Note that the purchase menu should have separate callbacks (when useful) since the user can't use the normal variables there.

Callbacks should apply to all cargoes except the purchase list, which has its own callbacks to explicitly make clear that vehicle variables are unavailable there.


Related issues

Blocks NewGRF Meta Language - Feature #1630: Allow using of proper units in callbacks / varaction2 New 2010-10-11

Associated revisions

Revision 1490:e5e22b5017ba
Added by Hirundo about 3 years ago

Add #1555: Support explicitly named callbacks.

Revision 1490:e5e22b5017ba
Added by Hirundo about 3 years ago

Add #1555: Support explicitly named callbacks.

Revision 1492:01debcf34e37
Added by Hirundo about 3 years ago

Change #1555: Convert existing constants to the new callback scheme.

Revision 1492:01debcf34e37
Added by Hirundo about 3 years ago

Change #1555: Convert existing constants to the new callback scheme.

Revision 1493:d92ddb9d90c0
Added by Hirundo about 3 years ago

Feature #1555: Allow 'default: xxx' in graphics blocks for all relevant features.

Revision 1493:d92ddb9d90c0
Added by Hirundo about 3 years ago

Feature #1555: Allow 'default: xxx' in graphics blocks for all relevant features.

Revision 1500:0d0405cb2e19
Added by Hirundo about 3 years ago

Feature #1555: Object callbacks.

Revision 1503:aa413f215ab5
Added by Hirundo about 3 years ago

Feature #1555: Named callbacks for houses.

Revision 1504:9ff1f8893b06
Added by Hirundo about 3 years ago

Feature #1555: Named callbacks for airport[tile]s.

Revision 1505:ebaff9e5400f
Added by Hirundo about 3 years ago

Feature #1555: Cargo callbacks.

Revision 1506:9b62fd938ddd
Added by Hirundo about 3 years ago

Add #1555: Random trigger callbacks for houses/industry tiles.

Revision 1500:0d0405cb2e19
Added by Hirundo about 3 years ago

Feature #1555: Object callbacks.

Revision 1503:aa413f215ab5
Added by Hirundo about 3 years ago

Feature #1555: Named callbacks for houses.

Revision 1504:9ff1f8893b06
Added by Hirundo about 3 years ago

Feature #1555: Named callbacks for airport[tile]s.

Revision 1505:ebaff9e5400f
Added by Hirundo about 3 years ago

Feature #1555: Cargo callbacks.

Revision 1506:9b62fd938ddd
Added by Hirundo about 3 years ago

Add #1555: Random trigger callbacks for houses/industry tiles.

Revision 1516:485fe6429aeb
Added by Hirundo about 3 years ago

Feature #1555: A 'callback' for rotor graphics.

Revision 1516:485fe6429aeb
Added by Hirundo about 3 years ago

Feature #1555: A 'callback' for rotor graphics.

Revision 1517:4e775fa7e6df
Added by Hirundo about 3 years ago

Doc #1555: Move documentation on old-style callbacks to a separate file.

Revision 1517:4e775fa7e6df
Added by Hirundo about 3 years ago

Doc #1555: Move documentation on old-style callbacks to a separate file.

Revision 1519:cffe40aff944
Added by Hirundo about 3 years ago

Doc #1555: Document callbacks for features 0x0B and up.

Revision 1519:cffe40aff944
Added by Hirundo about 3 years ago

Doc #1555: Document callbacks for features 0x0B and up.

Revision 1520:efd792c1e93c
Added by Hirundo about 3 years ago

Doc #1555: Document callbacks for houses and industries+tiles, plus some misc fixes and stuff.

Revision 1520:efd792c1e93c
Added by Hirundo about 3 years ago

Doc #1555: Document callbacks for houses and industries+tiles, plus some misc fixes and stuff.

Revision 1522:5665b88cb96d
Added by Hirundo about 3 years ago

Doc #1555: Document vehicle callbacks, add some constants as well.

Revision 1522:5665b88cb96d
Added by Hirundo about 3 years ago

Doc #1555: Document vehicle callbacks, add some constants as well.

Revision 1523:62580c07997e
Added by Hirundo about 3 years ago

Change #1555: Update regression test to include named callbacks.

Revision 1523:62580c07997e
Added by Hirundo about 3 years ago

Change #1555: Update regression test to include named callbacks.

Revision 1524:759229f98ce9
Added by Hirundo about 3 years ago

Doc: Document the graphics block, including callbacks (closes #1555)

Revision 1524:759229f98ce9
Added by Hirundo about 3 years ago

Doc: Document the graphics block, including callbacks (closes #1555)

History

#1 Updated by yexo almost 4 years ago

1. Menu graphics are a problem (you already notice that, it needs special syntax or manual cb handling by the user)
2. I've thought about this before, but it takes the freedom away from the user to have different callback implementations per cargo type. Or a different callback implementation depending on the date. With this syntax the only way to do that is:
switch (cb_x, cur_date) {
0..1990: cb_x_1;
cb_x_2;
}
switch (cb_y, cur_date) {
0..1990: cb_y_1;
cb_y_2;
}
switch (callbacks, cb_num) { // This one is implied by nml, not manually written)
1: cb_x;
2: cb_y;
}

While if you leave it to the user he could do:
switch (callbacks_1, cb_num) {
1: cb_x_1;
2: cb_y_1;
}
switch (callbacks_2, cb_num) {
1: cb_x_2;
2: cb_y_2;
}
switch (callbacks, cur_date) {
0..1990: callbacks_1;
callbacks_2;
}

The difference is not so obvious with only 2 callbacks, but with 5 callbacks the need to not duplicate the 0..1990 check becomes more obvious.

#2 Updated by Hirundo almost 4 years ago

In principle the user doesn't have to use this new scheme, if the current system fits better he is free to keep using it.

w.r.t. 1, they are already a problem. Exposing it is better than hiding it and confusing users later on, IMO.

To avoid point 2, I'd like to propose that 'return <expr>' also allows variables inside <expr>. I think this reduces the number of switch blocks needed for trivial callbacks. We could even allow this in the graphics block, just like it is possible to refer to sprite groups without an intermediary switch. This way, simple callbacks don't need any (explicit) switch block at all.

#3 Updated by yexo almost 4 years ago

OK, agreed. We'll just need to make it very clear in the documentation that the menu graphics are a special case. I'm still not sure about automatically writing the callback flags. While that does make it easy it can also cause confusion if the user wrote the callback flags manually and they're overwritten by the compiler.

Allowing "return <expr>" including variables seems like a good idea, we could silently rewrite it in a switch-block. Basically it'd just be:
switch (..., <expr>;) {
return; // Return computed value.
}

#4 Updated by Hirundo over 3 years ago

  • Target version changed from 0.1.0 to 0.2.0

This ain't gonna happen any time soon, I fear.

#5 Updated by Hirundo about 3 years ago

Before I make too many steps in this direction, I'd like to get a few issues ironed out. Please tell if you agree with my proposals:

- Callbacks with an equivalent property get the same name as the property
- If there is a separate callback for in the purchase list, it gets prefixed with "purchase_"
- 'default' and 'purchase' define the default and buy menu graphics. 'default_na' is additionally defined as type 0xFE for stations
- If there is a default defined in the graphics block, it is used for all unhandled callbacks. This to keep backward compatibility and allow manual callback handling. Else all unhandled callbacks chain to CB_FAILED.
- Cargo choice is handled via action3, i.e. one varaction2 per cargo. This, because there is no way (yet) to determine the cargo for stations.
- The existing railtype and purchase list pseudo-cargos will also need conversion to the new system. 'PURCHASE_LIST' will become 'purchase' and I suggest to make all railtype stuff lowercase. A (temporary) old->new conversion table with warnings should do in this case, IMO.

#6 Updated by Hirundo about 3 years ago

Currently done:
  • basic implementation
  • vehicles
  • railtypes
TODO:
  • documentation
  • regression testing
  • stations
  • houses
  • industry tiles / industries
  • airport tiles / airports
  • cargos
  • removing the old constants, when grfs are updated

#7 Updated by Hirundo about 3 years ago

  • Tracker changed from Feature Request to Feature
  • % Done changed from 0 to 40

#8 Updated by Hirundo about 3 years ago

  • % Done changed from 40 to 60

Houses, industries+tiles, cargos, airports+tiles added in recent commits.

#9 Updated by Hirundo about 3 years ago

  • Status changed from New to Closed
  • % Done changed from 60 to 100

Applied in changeset 759229f98ce9.

Also available in: Atom PDF