programmatic item effects

[ninjaman0722]

I want to add programmatic item held effects, use effects, and the conditions for those items effects to make the API better for battle simulators (what i am personally using it for).

i want to take a shot at implementing it myself if someone isn't already working on something similar.

[ninjaman0722]

if there is no specific preference for how this would be implemented this is how i would do it

there would be 4 new tables, item_effect_triggers, item_effect_types, item_effect_targets, and item_mechanics

1. item_effect_triggers

Defines the specific "event"

id: Primary Key.

identifier: The slug (e.g., on-hp-below-50, on-contact-taken, on-entry, on-move-selection, end-of-turn).

2. item_effect_types

Defines the mechanical change the item applies to the game state.

id: Primary Key.

identifier: The slug (e.g., hp-recovery, stat-multiplier, damage-reflection, status-cure, prevent-fainting).

3. item_effect_targets

Defines who the effect is applied to

id: Primary Key.

identifier: The slug (e.g., holder, attacker, field-ally, field-opponent).

4. item_mechanics

this connects items to their logic

item_id: FK to items.

version_group_id: FK to version_groups

trigger_id: FK to item_effect_triggers.

effect_type_id: FK to item_effect_types.

target_id: FK to item_effect_targets.

value: The raw numerical data (e.g., 25, 1.5, 0.166).

value_type: Defines how to interpret the value (e.g., percent-max, multiplier, flat-hp, probability).

im going off based on how i understand the API to work after looking over it for a bit, so i may be way off on how it would actually be implemented XD

[phalt]

Do you mean - endpoints that provide game-style functionality?

PokeAPI is a read-only API. We generated JSON files from a local database and then publish them statically. No part of the API is connected to a live application server. This is mostly so we can keep costs down and avoid computation costs for the billions of API hits we get...just to serve static files 😆

PokeAPI is not intended as a game-engine and is just read-only data. You're more than welcome to propose a separate project and use the expertise here of contributors (we know so so much about the games!) though.

[notblisy]

Do you mean - endpoints that provide game-style functionality?

PokeAPI is a read-only API. We generated JSON files from a local database and then publish them statically. No part of the API is connected to a live application server. This is mostly so we can keep costs down and avoid computation costs for the billions of API hits we get...just to serve static files 😆

PokeAPI is not intended as a game-engine and is just read-only data. You're more than welcome to propose a separate project and use the expertise here of contributors (we know so so much about the games!) though.

I think the information ninjaman is proposing is adding detailed information on items as endpoints that describe how they're triggered, what those triggers do, and who those triggers effect.

Right now that information is only really contained in item_prose.csv and item_flavor_text.csv which are text blurbs.

The system they've shown here seem to be similar to how the item_fling_effects would work currently. I think this info being added would only be beneficial to the APIs data.

The only suggestion I would have to this, @ninjaman0722, is to add a past value to "item_effect_triggers", "item_mechanics", and maybe "item_effect_targets".

Item triggers definitely change over time, plenty of berries have changed their trigger HP. For example, Figy Berry went from 1/2 HP trigger to 1/4 HP trigger in XY->SM.

Item effects have also changed a lot. I'm not sure if targets ever has, we'd have to look that up.

[phalt]

The system they've shown here seem to be similar to how the item_fling_effects would work currently. I think this info being added would only be beneficial to the APIs data.

Far clearer to me now, thanks. I think if it is just read only data that the API supplies then it make sense to add.

[ninjaman0722]

I think the information ninjaman is proposing is adding detailed information on items as endpoints that describe how they're triggered, what those triggers do, and who those triggers effect.

This is exactly right! with how pokeapi is now, i still have to manually write out essentially my own item database in my program for it to work. if i have to make a database with what all items do i might as well contribute to a project that does most of this for me anyway lol

The only suggestion I would have to this, @ninjaman0722, is to add a past value to "item_effect_triggers", "item_mechanics", and maybe "item_effect_targets".

great catch! thanks for pointing this out! i know bulbapedia does a great job at separating gen differences so i will have to look into it a bit.

if i am to do this i would definitely appreciate all the help i can get. ive never really looked at the back end of the api until yesterday and its a lot XD

[notblisy]

Smogon also does a good job on item triggers/effects if you feel the need to crosscheck bulbapedia whenever, and I find it a bit easier to navigate.

[ninjaman0722]

i have come up with an example of what it would look like for a sitrus berry (using bulbapidia as a reference)

item_id | version_group_id | trigger_id | effect_type_id | value | value_type | is_consumable
135 | 5 | 2 (hp-below-50) | 1 (hp-recovery) | 30 | flat | 1
135 | 5 | 10 (bag-use) | 1 (hp-recovery) | 30 | flat | 1
135 | 8 | 2 (hp-below-50) | 1 (hp-recovery) | 25 | percent-max | 1
135 | 8 | 10 (bag-use) | 1 (hp-recovery) | 25 | percent-max | 1
135 | 8 | 12 (forced-use) | 1 (hp-recovery) | 25 | percent-max | 1 (this covers Fling, Pluck, and Bug Bite,)

[notblisy]

I'm not a maintainer, but this all makes sense to me.

I do think past values typically use generation ID rather than version groups, so a maintainer might need to weigh in on that. I actually prefer it, though, as it lets us account for changes more with granularity.

[ninjaman0722]

Ok so already this is too simple, so instead of 4 we do 7 new tables

4 Vocabulary Tables

​##item_mechanic_triggers: Defines the timing/window of evaluation.
​Examples: on-hp-change, end-of-turn, on-damage-taken, on-manual-use (Bag), passive-constant.

​##item_mechanic_contexts: Defines where the item can be used.
​Examples: held-in-battle, bag-in-battle, overworld-menu.

​##item_mechanic_effect_types: The action performed.
​Examples: hp-recovery, stat-multiplier, status-apply, trigger-evolution, modify-duration.

​##item_mechanic_targets: Who the effect applies to.
​Examples: self, attacker, party-member, field-global.

3 Core Logic Tables

##item_mechanics: Links item_id to version_group_id, trigger_id, and context_id.
​Fields: id, item_id, version_group_id, trigger_id, context_id, is_removable.

​##item_mechanic_conditions: ​Requirements linked by mechanic_id. Supports logical grouping.
​Fields: mechanic_id, condition_type (e.g., hp-threshold, species-id), operator (==, <=, etc), value, group_id (for AND/OR logic).

##​item_mechanic_effects: The result of a successful trigger.
​Fields: mechanic_id, effect_type_id, target_id, value, value_type (flat, percent-max, multiplier), probability, is_consumed.

This should cover everything (hopefully)

[ninjaman0722]

i got an example here now for the sitrus berry (holy crap what a headache to get this to work XD)

    "mechanics": [
        {
            "version_group": 5,
            "trigger": {
                "name": "on-damage-taken",
                "url": "http://localhost/api/v2/item-mechanic-trigger/1/"
            },
            "context": {
                "name": "held-in-battle",
                "url": "http://localhost/api/v2/item-mechanic-context/1/"
            },
            "conditions": [
                {
                    "condition_type": "hp-threshold",
                    "operator": "<=",
                    "value": "50",
                    "group_id": 1
                }
            ],
            "effects": [
                {
                    "effect_type": {
                        "name": "hp-recovery",
                        "url": "http://localhost/api/v2/item-mechanic-effect-type/1/"
                    },
                    "target": {
                        "name": "self",
                        "url": "http://localhost/api/v2/item-mechanic-target/1/"
                    },
                    "value": "30.00",
                    "value_type": "flat",
                    "probability": 100,
                    "is_consumed": true
                }
            ]
        },
        {
            "version_group": 11,
            "trigger": {
                "name": "hp-change",
                "url": "http://localhost/api/v2/item-mechanic-trigger/2/"
            },
            "context": {
                "name": "held-in-battle",
                "url": "http://localhost/api/v2/item-mechanic-context/1/"
            },
            "conditions": [
                {
                    "condition_type": "hp-threshold",
                    "operator": "<=",
                    "value": "50",
                    "group_id": 1
                }
            ],
            "effects": [
                {
                    "effect_type": {
                        "name": "hp-recovery",
                        "url": "http://localhost/api/v2/item-mechanic-effect-type/1/"
                    },
                    "target": {
                        "name": "self",
                        "url": "http://localhost/api/v2/item-mechanic-target/1/"
                    },
                    "value": "25.00",
                    "value_type": "percent_max",
                    "probability": 100,
                    "is_consumed": true
                }
            ]
        }
    ]

[phalt]

"operator": "<=",

You should make this more generic with a constant - I know that for 90% of programming languages this will make sense, but there is a few esoteric languages out there that will use different syntax. A table of constants like LESS_THAN, EQUAL_TO etc would be far better.

[ninjaman0722]

i believe i got a good setup in #1466

please look over it and let me know of anything that needs changed or whatever (also im not sure if i am using version_group_id correctly but its easy to change at this state XD)

also just noticed i wrote EQUALS and NOT_EQUAL instead of EQUAL_TO and NOT_EQUAL_TO like an absolute bafoon