Simutrans Squirrel 3.2 — Script API migration, compatibility and developer refer

[victor_18993]

The Squirrel 3.2 migration for Simutrans Standard is now complete, and I have prepared a public developer reference covering the migration and its compatibility implications.

The runtime changes were integrated in trunk in r12165–r12168, with r12168 completing the accompanying documentation.

The main point for scenario and AI authors is that this is a Squirrel runtime update, not a redesign of the Simutrans Script API.

The migration was deliberately implemented so that the existing public Script API remains stable:

• no registered Script API function was added, removed or renamed by the runtime migration;
• no public parameter list or default-argument behaviour changed;
• existing compatible scenarios and AI scripts should not require wholesale rewrites;
• old savegames containing script state were explicitly tested;
• no pakset changes are required.

There is one script-visible semantic difference worth particular attention: table iteration order may differ under Squirrel 3.2 because the string hashing behaviour changed. Scripts that require a deterministic or specific order should therefore not rely on incidental table iteration order.

The documentation also covers:

• the Squirrel 3.2 runtime provenance;
• the internal C++ embedding changes;
• the
  
  Code Select Expand
  sq_getinstanceup() adaptation;
• Code Select Expand
  bindenv support;
• the new
  
  Code Select Expand
  table.map functionality;
• compatibility guidance for scenario and AI authors;
• examples;
• Script API stability checks;
• migration validation results;
• the relevant SVN revisions.

Final validation of the integrated migration included:

• 284/284 full regression tests;
• 10/10 VM-specific tests;
• 2/2 orphan tests;
• no new Squirrel errors.

I am attaching the English developer reference as the canonical technical documentation.

A Spanish version has also been prepared from the reviewed Spanish documentation integrated with the migration.
This documentation applies to Simutrans Standard builds containing r12168 or later.

I hope this is useful both for people maintaining existing scripts and for future developers working on the Simutrans scripting layer.

[victor_18993]

Updated attachment uploaded.

The Squirrel 3.2 documentation package now includes English, Spanish, German and Japanese, with a standardized international localization structure.

English remains the canonical technical source; Spanish is human-reviewed, while German and Japanese are clearly marked as AI-assisted translations pending human review.

The package also includes XLIFF, TMX and shared terminology data, so future translations can follow the same workflow and the documentation can be converted more easily for use in the Simutrans wikis and other publication formats.

[Andarix]

http://www.squirrel-lang.org/squirreldoc/index.html