Sphere colors are hardcoded right now. The preferred indexing is as follows:

• Negative numbers are used for special balls (lightning, wild, fireball).
• 0 should be reserved for the vise in paths and for the empty sphere in shooters.
• Positive numbers are normal sphere colors.

A given sphere should have at least the following parameters:

• sphere image file,
• text image file (for broken spheres),
• color bomb image file,
• next sphere image file (for shooters),
• RGB color (for reticals) -> defined in main.lua:23, used in Shooter.lua:118,
• a list of spheres which match the given sphere -> Session.lua:98,
• an interaction type on touch (append to the chain, destroy surrounding spheres etc.) -> ShotSphere.lua:41,
• an interaction type on shoot (lightning balls work instantly) -> Shooter.lua:70,
• a particle path for idle spheres in the shooter,
• a sound event when the sphere is shot,
• a sound event when the sphere touches a train,
• whether a sphere can appear in the shooter.

Additionally, when implementing remember to look at the sphere counting algorithm (Session.lua:46, Session.lua:82).

This is to maintain the convention.

Seeing the Speed Shot beam gives me these ideas:
Option 1 is to have it always be extended
Option 2 is to have it abruptly cut (like in vanilla 1/AR).
Option 3 is to have it be squished depending on how close the nearest sphere is (Zuma/Luxor 2).

Allow to create, based on some criteria such as position or color, an instance of a class that would contain a list of spheres with which you can do varius stuff, such as change their color or destroy them.
This would be useful for most powerups which mess with spheres. Currently, all that stuff is in Session.lua which isn't the best place to store all these functions.

Ditch a list of levels, move their data to levels itself (name and music), and instead make a new data structure in level data. For example, it would contain:

• a checkpoint flag which would work like it works right now
• a list of levels which would be unlocked when the level is finished
• whether the game should go back to the map selection screen upon completing a level, or rather instantly teleport to another level, such as a cutscene or as a prevention mechanism to select something else

Also, levels could be assigned their widget IDs so they would provide user interaction.

Maybe there could be a json file (with some code in the program that makes it work) that determines/grabs:

• If the RPC is enabled.
• What ID should the mod has.
• Difficulty (once it gets implemented)
• What levels/menus/etc use for the image assets.
• If there is no json file then the RPC is off.

Each map would contain objects, previously defined by the user. The objects can be common (like the OG pyramid or sphere reflectors) or be special to just one map. Each object would be then placed on a position, and could be given a path to move on.

Objects could also interact with shot spheres, for example applying a gravity field, bouncing it, changing a color or destroying it.

New objects could be spawned and existing could be deleted. Objects may spawn more objects, particles or powerups on certain circumstances.

This is for naming consistency sake.

Sphere modifiers would alter newly spawned spheres.
Example in level file:
-> Replace this:

    "colors": [1,2,3,4],
    "colorStreak": 0.5333333333333333

-> to this:

    "sphere_generation": {
        "colors": [1, 2, 3, 4],
        "color_streak": 0.5333333333333333,
        "modifiers": [
            {
                "modifier": "stone",
                "chance": 0.05
            },
            {
                "modifier": "double",
                "chance": 0.15
            }
        ]
    }

The modifiers field can be omitted if no modifiers are provided.
The modifiers would be stored in config/sphere_modifiers/<name>.json files, similarly to powerup generators.
Example modifier data:
config/sphere_modifiers/stone.json:

{
    "replace_with": [
        {
            "color": -5
        }
    ]
}

config/sphere_modifiers/double.json:

{
    "replace_with": [
        {
            "color": 11,
            "conditions": [
                {
                    "condition": "color",
                    "color": 1
                }
            ]
        },
        {
            "color": 12,
            "conditions": [
                {
                    "condition": "color",
                    "color": 2
                }
            ]
        },
        [...]
    ]
}

Description:

1. Level files. Each generated sphere has a chance chance to have a given modifier applied. One sphere can get modified multiple times.
2. Modifier files. The only field in the root object is replace_with. It contains a list of items - each item can have conditions. When an item is chosen, the iteration stops and the effect is applied. Currently the only effect is a color change, but the format may change in the future.

Boot screen pulls incorrect constant global version value, showing 1.0.0 even in beta 1.0.1. Easy fix by changing main.lua.

The current config.json file is a huge 37 KB file which is still growing. Soon, it might be hard to make any changes, and although, there is an editor planned, it's still a pretty long way until we actually start making it. Until then, it would be nice to split all these different tables to different files, in order to maintain readability.

Things that will be needed to make it work:

1. This command: curl https://api.github.com/repos/jakubg1/OpenSMCE/tags executed in Command Prompt will result in a list of versions being displayed.

• Get the first element's name field in order to obtain the latest released version.
• Compare it with the software version.
• If it doesn't match, prompt that there's an update available.

2. Make curl work on the engine.

• This is still to be worked out yet.

When one loses a level and exits the game before the Foul message pops up, the game can be loaded and played normally. This makes people be able to cheat, which shouldn't be the case.

If a sphere is shot before the first sphere in a chain, the chain moves a seemingly random number of pixels (forward or backward). This should not occur.

Tested with newly spawned chains in vertical arrangement. Does not happen in some cases.

In case of a crash, you have still a chance to save your progress (this doesn't work yet, see #20). However, when an engine is stuck in an infinite loop, or there is a power outage, you can do nothing.

An autosave with a configurable delay would be a nice touch that could save some hassle.

When the pyramid is breached and the level is failed, sometimes the shooter still works. That shouldn't be the case.

The default main module file states that:

-- This is a default module file for OpenSMCE games.
-- You can override any, or all of the methods below.

However, this is only partially true. You can't make a module which replaces only one of the functions, you have to make a module which replaces all of the functions. This is because the default functions are ignored at all when anything is found in the game module.
Solution: Always load the default module first and then replace them with functions from the game module.

This affects ResourceManager, WidgetManager, EventManager, ColorManager and RuntimeManager.

Most notably add WidgetManager and EventManager.

Right now, the UI is actually scriptable but it's a made-up custom script syntax. Because there is already some Lua module stuff going on, I think it's time to make UI scriptable also via Lua. This has actually quite a few benefits:

• The custom script code will be shredded, and so it will probably be the game event code too
• No need to calculate and store the so-called widget variables
• No need to store HUD paths in config anymore

This has of course a disadvantage - Lua knowledge would be slightly more mandatory for altering such code. This is especially important if one would want to create a custom UI for their game.
Furthermore, I don't plan any direct Lua scripting support in an upcoming game editor yet.

Difficulties are stored in runtime.json in a particular game's main directory, however they are not used.
Change the type from integer to string.
Difficulties alter some values. Consider implementing them similarly to Luxor 2's system. Example from difficulty.gvf (one of the difficulties):

{
   Directory           = "adventure"
   StartStage          = 1
   FinalStage          = 14
   StartingLives       = 4
   CoinsForLife        = 30
   MinCollapseCount    = 3
   SpeedScale          = 0.50
   StageStepSpeedScale = 0.019
   ScoreScale          = 1.0
   Timescale           = 1.0
   TimescaleWarmup     = 1.5
   LivesBonus          = 50000i64
   PerfectBonus        = 10000i64  
   Downgrade
   {
      LossDelay        = 1
      Reductions       = 5
      MidSpeed         = -5.0
      MinSpeed         = -0.2
      SpawnStreak      = 20
   }
}

If one implements such values like here (preferably in the main game config file), there's no need to do it separately in that case.

Should be self-explainable.

When a sound that loops is playing and a player quits to main menu, the sound can still be heard.

When multiple looping sound events of the same file are active and one of it is stopped, all instances are stopped.
The solution is to make the sound play function return a handler and use it to stop that particular instance.

Replace them temporarily with hardcoded values, and think how should management look in the future.

Take a look at the code and rename the variables accordingly.

Classes known to have their settings named settings:

• Shooter
• Scorpion

Classes known to have their settings named config:

• Game
• Local variables in Shooter and other classes which handle the powerup and sphere data

TL;DR: Rename settings to config in Shooter.lua and Scorpion.lua.

On the straight parts, spheres can glitch and be weirdly rotated. This is an example image:

This includes for now:

• Sphere stacks
• Powerups on spheres
• Sphere effects (freezing, poisoning etc.)

I need to change it soon.

Having certain levels (or whole game) to have a permanent speed shot is a thing under consideration. It will be nice to have it at some point.

An almost full list of what the engine needs to do in order to consider Luxor 1 support fully finished:

Beta 2.0.0

• Game menu
• Speed shot beam
• Spheres on the menu screen
• Credits menu
• Settings menu
• Saving level state (see #8)

Beta 2.1.0

• Shadows, glow and trails should appear on and behind gems, coins and powerups
• Lightning/fireball particles when in the shooter

Beta 2.2.0

• How to play screen
• Powerup weighting (see #10)

Beta 4.0.0

• Highscore table
• Level map
• Profile menu
• How to play screen appearing upon starting a new game

Beta 4.8.0

• Game win widget

This would be primarily used for sound positioning to make sounds more pleasant.

If possible, integrate the engine with Discord, for it to say

<Game Name>
<Level xx-xx>

Possibly add also life count, progress or score.

[Suggested by Ignatius]

It is reported that it happens on speeds 900 and higher.

In short, such class would be a graphical representation of a Sphere and should include such features as idle particle or shadow.

It should be used by SphereGroup, Sphere, ShotSphere and Shooter.

This would simplify drawing code and remove all inconsistencies.

If you shot a sphere onto any sphere train already on the board, and pause and exit the game right after the shot sphere hits the train, you would crash the game upon trying to load a level state in such a way.

In ShotSphere.lua, in serialize() function, you can find this piece of code:

		hitSphere = {
			pathID = 1,
			chainID = 2,
			groupID = 1,
			sphereID = 8
		}, -- TODO: add an indexation function in Sphere.lua to resolve this problem

This is a placeholder, and should certainly not be there. Replacing this with a proper working indexation code should resolve this issue.

A powerup generator would be a JSON file containing spawnable powerups and corresponding chances and spawn conditions.

Some important changes would be made as a result:

• Spawn weights no longer would be needed to be defined via config.json
• Colorized powerups would cease, and they would be split into variants for each color
• Each level would need to have a powerup generator specified instead of a list of available powerups

Example:

vanilla_generator.json

{
  "entries":[
    {"type":"powerup","name":"wild","weight":1000},
    {"type":"powerup","name":"fireball","weight":500},
    {"type":"powerup","name":"lightning","weight":500},
    {"type":"powerup","name":"stop","weight":1000},
    {"type":"powerup","name":"slow","weight":1000},
    {"type":"powerup","name":"reverse","weight":1000},
    {"type":"powerup","name":"speedshot","weight":1000},
    {"type":"powerup_generator","generator":"vanilla_generator_colorbomb.json","weight":500}
  ],
  "fallback":[
    {"type":"powerup_generator","generator":"vanilla_gem.json"}
  ]
}

vanilla_generator_colorbomb.json

{
  "entries":[
    {"type":"powerup","name":"colorbomb_1","conditions":[{"type":"color_present","color":1}]},
    {"type":"powerup","name":"colorbomb_2","conditions":[{"type":"color_present","color":2}]},
    {"type":"powerup","name":"colorbomb_3","conditions":[{"type":"color_present","color":3}]},
    {"type":"powerup","name":"colorbomb_4","conditions":[{"type":"color_present","color":4}]},
    {"type":"powerup","name":"colorbomb_5","conditions":[{"type":"color_present","color":5}]},
    {"type":"powerup","name":"colorbomb_6","conditions":[{"type":"color_present","color":6}]},
    {"type":"powerup","name":"colorbomb_7","conditions":[{"type":"color_present","color":7}]}
  ]
}

How would it work:

First, upon generator data usage, all powerups that do not meet the conditions (if specified) should be removed from the list. Then, from the remaining entries, pick one. When no entries are left, use fallback generator if specified. Else, don't spawn anything.

Notes

• When weight is omitted, it defaults to 1.
• When conditions are omitted, no checks are performed.
• Example condition types:
  • color_present - check if a given color exists on the board.
  • level_number - check if the current level is a number that equals/is in range of number.

Much like spheres generated on the board, each level should also have its shooter generator. Generators may change during the level if for example the danger flag is active.

Example types of generators:

• random
• random biased on front (danger)
• generate a sequence (1-long sequence makes it also viable for a single color generator)

For a puzzle level, there would be a sequence generator as well as a sphere limit for shooters.
Generators should have parameters.

Instead of map sprites having a background flag, and path nodes having a hidden flag, there could be layers starting at 1, which would tell in which order spheres and map sprites should be rendered.

Example for current games:

• Layer 1 would be rendered first, thus falling on the background. Every sprite with background set to true would fall to layer 1.
• Then, spheres on layer 1 would be rendered. The layer 1 would be for nodes with hidden flag set, because...
• Layer 2 is where all the foreground sprites would be (background flag set to false). This includes pyramids and path masks.
• At the end, spheres on layer 2 would be rendered (hidden flag set to false).

Implications:

• Path nodes would need to have a new flag, which would determine if spheres around that node can be shootable.
• I haven't came up with an idea how would the sphere coloring (dimming when in tunnels) work, and how bonus scarabs and scorpions should know whether they can emit particles.

The beam root should be exactly in the center of where the sphere should be. However, it's shifted up.

When a Collectible is on the board and the player exits to main menu and reenters the game, the Collectible particles are still there and will not despawn.

Instead of just an amount of destroyed spheres, some other types can be used too, i.e. score.

Comment from @xregexx on SM Discord server:

also, time elapsed, gems collected, spheres/vises spawned, appropriate-colored spheres destroyed. and something more specific like "make X combo/chain T times", "destroy X spheres at once with this particular powerup T times", "keep the spheres enough far from danger zone for enough long time" and so on
also, winConditions stacking

Since commit 7dd7857 there is now a more optimized version of the sphere drawing routine. I want to optimize it further.

• Utilize SpriteBatch:
  • The following textures will have their SpriteBatch object:
    • All sphere textures (image field of each sphere definition object in config.json)
    • Sphere shadow image
    • Potentially sphere dimmer?
  • When a Sphere appears on the track, add a sprite to a corresponding batch and retrieve the ID.
  • When a Sphere leaves the track, "remove" the sprite by moving it to a specific position, as specified here.
  • Each draw, we want to update all sphere sprites to a new position.
  • I don't know in which class the batches will be stored yet. (Probably Map.lua)
  • Every specified time (one minute?) the batches will be emptied and all Spheres will again be re-added. This is to remove all pseudo-removed empty batch sprites.
• Since we can't color spheres one by one in sprite batches, the sphere dimming will be provided by overlaying a black circle over the sphere with an appropriate transparency.

I don't exactly know how to replicate this bug, but I had a somewhat incomplete data folder so I re-extracted Luxor 1's mjz files. (later on I realized that QuickBMS somehow did not extract the main files, which is a non-OpenSMCE problem).
They turned out mostly the same, but re-doing the conversion process caused the program to not extract all the files.
img: https://cdn.discordapp.com/attachments/455322611178668032/735763257935003690/unknown.png

Similarly to spheres, powerups should also be defined.

A given powerup entry should hold the following:

• Name when picked up
• Particle/sprite/path (the way powerups are rendered will change in Beta 1.1 and a few times in future versions too)
• Sound when picked up
• Effect (example effects below)
• Weight (chance of dropping)

The entry index should be an internal powerup name, like it occurs in main.lua header.

Example effects:

• replace current sphere (wild, lightning, fireball) - parameters: sphere color
• apply a certain speed for a certain amount of time (slow, stop, reverse) - parameters: speed, time
• destroy a certain color (color bomb) - parameters: color
• apply speed shot (speed shot) - parameters: time, speed(?)
  Future versions:
• summon a scorpion - no parameters(?)

Any game could have a set of Lua scripts that would be assigned per game instead of per engine. This could enable extra flexibility for value configuration.

Example:
Take this from <game>/config.json:

"sphereBehaviour":{
   "collisionSpeed":-200
}

Instead, this could be an equivalent function in, let's say, <game>/scripts/sphereBehaviour.lua:

function collisionSpeed(comboLv, chainLv)
    return comboLv * -200
end

UI could be scripted in a similar way. However, this would need to have the game event system reevaluated and most of UI system functions should be provided in order to make game UI script files as simple as possible.

This would also allow to configure some tough formulas that are hard to be represented in JSON, such as functions whether a given match should spawn a coin or a powerup.

This feature will be implemented late, probably during the process of writing an engine documentation or even later.

The functionality is not there in Beta 2.0.1, however the button is. This should be fixed as quickly as possible in order not to mislead the people.

When one exits the game during the level progress. This applies to:

• Sphere chain arrangement and positions
• All collectibles' positions
• Current shooter ball colors
• Level progress, score and stats

Additionally:

• Bonus scarab
• Scorpion

For now two things. Disable RPC, and add an option to go back to the boot screen when you exit a Game.

This does not require taking an action in most cases, but this would be visible in tight spaces.

Because of how the current angle determination algorithm works, the spheres are "looking" at the warp destination when before a warp node and at the warp node when past the warp destination.