beyond-all-reason / beyond-all-reason/RecoilEngine

[FR] Add `Spring.SpawnWeaponExplosion`

Open
#882 2 comments 0 reactions 0 assignees View on GitHub
area: Lua API enhancement good first issue
Dominant language
C++
Stars
679
Forks
290
Avg merge
3d 2h
Merged PRs (30d)
40

Description

### User story

I am a newbie modder who wants to spawn an explosion of an existing weapon, that's it.

### Deficiencies of existing interfaces

`Spring.SpawnExplosion` exists but it has a bad interface for this. It defaults to 0 aoe and 0 damage and 0 edgeeffectiveness and 0 literally everything. It doesn't require to pass a weaponDefID (so you can get weird ghost explosions with no FX), but even if you do pass one, it still doesn't affect the default damage/aoe/ee/etc so you need to replicate them manually. The flat (non-table) version also has the weaponDefID as far as the 16th parameter, being considered less important than such things as `gfxMod` and `impactOnly`. Using this function is tedious and error-prone.

`Spring.CreateProjectile` combined with either `ttl=0` or `Spring.DestroyProjectile` seems to spawn an explosion with the correct damage etc but actually does more than that; it triggers `gadget:ProjectileCreated/Destroyed` which may make assumptions and have side effects.

### Proposal

Add `Spring.SpawnWeaponExplosion(weaponDefID, x, y, z, rest of args)`. The `weaponDefID` is mandatory and affects the default damage/aoe/ee/etc. The rest of args are in a similar format as `SpawnExplosion` (ie. table or flat) but the flat version has them in a more sensible order (which is a vague term and may be discussed).

Contributor guide

Open the contributing guide

Research direction

Start by comparing the existing Spring.SpawnExplosion and Spring.CreateProjectile interfaces, including their documented arguments and side effects. Define the new Spring.SpawnWeaponExplosion entry point around a mandatory weaponDefID and weapon-derived defaults; done means it supports table and flat forms without triggering projectile lifecycle callbacks. The flat argument order remains open for discussion.

Written by the indexing model from the issue text.

Assessment

Tech stack
cpp
Domain
api, game-dev
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.