This is an incompatible change to the ASH functions which specify flags. I want to change them to be more rational.
Also, I'm adding some functions that let you specify the casting count.

Let's look at the current ASH API for Sweet Synthesis. I want to adjust it to allow for multi-casting the skill, as appropriate.. I.e., being able to say "I want to spend X of candy1 and X of candy2 to get X*30 turns of the resulting effect."

Flags are a bitmask used to restrict which candies to consider

Code:
    available       1   default 1 in ronin/hardcore, 0 out of ronin
    nochocolate     4   default 1
    useblacklist    8   default 1
I chose those values so that if all are 0 - don't consider availability, allow chocolate, don't look at blacklist - no filtering is done; all candies in a particular tier are considered. AS you notice, however, the "default" flags are not 0; they are 13 in hardcore/ronin, 12 outside of ronin.

*** I wonder if it would be clearer to jigger those such that a flag is 0 in the "normal" case and 1 if you want something unusual? In other words:

Code:
    available       1   default 1 in ronin/hardcore (available only), 0 out of ronin (buying is OK)
    chocolate       2   default 0 (1 to consider using chocolate)
    noblacklist     4   default 0 (1 to not use the blacklist)
(The previous flag 2 was "deprecated". It is now removed.

This would make the default 0 if you are out of ronin, 1 if you are in hardcore or ronin

The "no filtering" setting would then be !available | chocolate | noblacklist = 12. That is just as easy for me.

All sweet synthesis functions that involve selecting candy have a version with an optional "flags" argument.
I seriously doubt that anybody is using those versions.
If people are using those methods, changing the chocolate & blacklist flags will break.

I might do it anyway.

The functions:

void load_sweet_synthesis_blacklist()

If you want to use the blacklist, you have to load it from the property. Internally, the Sweet Synthesis GUI loads the blacklist when it is created and reloads it when the property changes (it has a listener which fires in that case). In ASH, presumably you have control if/when you change the property. I wanted to avoid having all the internal methods having to constantly reload the blacklist - especially since they are called by the GUI, which loads it exactly when required.

I think I will get rid of this and make the ASH functions that might or might not use it load, as needed. A little extra overhead, but easier for the ASH coder.

item [int] candy_for_tier( int tier )
item [int] candy_for_tier( int tier, int flags )

These are for ASH programs that want to do their own selection of candies. Don't need to include versions looking for "count". That is only significant if you want to use candy in inventory. The ASH program can use item_amount() to see how many there are.

item [int] sweet_synthesis_pairing( effect, item candy1 )
item [int] sweet_synthesis_pairing( effect, item candy1, int flags )

Given an effect and candy1, returns a list of potential candy2 that, when synthesized with candy1, gives the desired effect. Potential candy2 come from the same list candy_for_tier() returns, given the flags. Do we need to let you specify a count? I don't think so. Again, the ASH program selected candy1 - perhaps based on inventory availability - and, if so, it can assess the available quantity of each candy2, if desired.

boolean [item] sweet_synthesis_pair( effect );
boolean [item] sweet_synthesis_pair( effect, int flags )

These return a set of two candies that will give the desired effect. We apply the flags to restrict which can be considered. You'll end up with the "cheapest" pair of candies. Unless you are using only "available" candies, you will always get a pair. What if you want to cast it 5 times don't have enough available? If the ASH program cares about availability, I think it is up to the program to look at inventory after getting a pair and decide how many castings it can get. If it wants more, it can go get another pair.

effect sweet_synthesis_result( item candy1, item candy2 )

Returns the effect from synthesizing two candies. Informational.

boolean sweet_synthesis( effect )
boolean sweet_synthesis( effect, int flags )

It is appropriate to specify the number of castings desired for these. Internally, they use sweet_synthesis_pair to select a pair of candies.

boolean sweet_synthesis( item candy1, item candy2 )

This should also have a version with a casting count. You specified the items, so no loop: we already "acquire" the items, which will fail if unsuccessful.

Proposed/intended actions:

*** redefine flags:

Code:
    available       1   default 1 in ronin/hardcore (available only), 0 out of ronin (buying is OK)
    chocolate       2   default 0 (2 to consider using chocolate)
    noblacklist     4   default 0 (4 to not use the blacklist)
Default is 0 if you are out of ronin, 1 if you are in hardcore or ronin.

*** eliminate new method I added yesterday:

void load_sweet_synthesis_blacklist()

I'll make the ASH functions that depend on the flags, load the blacklist if needed.

*** new methods:

boolean sweet_synthesis( int count, effect )
boolean sweet_synthesis( int count, effect, int flags )

If flags require "available", these will have to loop.

boolean sweet_synthesis( int count, item candy1, item candy2 )