Skip to content

Migration from SFS2X

If you have previous experience with SmartFoxServer 2X or you're interested in porting an existing SFS2X project to SmartFoxServer 3, this document provides an overview of the changes you will encounter and a few recommendations for migrating your code.

Client Side

All client side APIs have been rewritten from scratch making use of the latest runtimes available (e.g. Java 21+ for Java, .Net 8+ for Unity/Godot and so on). However the API interface was kept very similar to SFS2X's, so the amount of changes required to port older code to SmartFoxServer 3 is going to be relatively low.

Some of the basic changes require modifying package or namespace imports, as a few objects and methods have been renamed or slightly moved around to best accommodate the new API structure.

A few things to keep in mind:

  • the ConfigData object has been expanded and reorganized as the number of settings has increased. Make sure to check the specific API docs to learn all the details
  • you no longer need to manually start an SSL session after connecting, instead just specify if you want to use SSL via ConfigData.useSSL
  • all default port numbers have been changed so you can run SFS2X and SmartFoxServer 3 locally (or remotely) without port collisions. More details are provided here

» Additional resources:

  • Check the Login Phase tutorial for a quick look at the basics of connecting and logging in
  • Check the API setup and code examples in our Client API section from the left hand menu
  • Also check the new example packs from our main website TODO

Server Side

While Extensions have been improved under many aspects behind the scenes, the development approach remains the same. You will extend the top level SFSExtension class and create a number of event and request listeners based on your game requirements, as in SFS2X.

You can take a look at this article to see how it works. What you will need to keep in consideration are the following changes:

  • Package names: in SFS2X most the root of many useful packages was under com.smartfoxserver.v2.*, while now we've dropped the 'v2', so you will need to adjust your imports.

  • Threading: since SmartFoxServer 3 uses virtual threads there is no need to create or delegate the task being executed by a request to another thread or thread-pool, even when dealing with databases, HTTP calls or other blocking calls. If your old code was using additional thread pools, remove them and refactor the code. As an added bonus Extensions will become simpler and easier to maintain.

  • Schedulers: the previous point is valid for Task Schedulers as well. There is no need to instantiate custom schedulers, just use the main scheduler provided by the SFS3 API. It will handle however many tasks you need.

  • Shared libraries: dependencies that can be reused by multiple Extensions should go in extensions/_shared, which is the equivalent of the old lib/ folder in SFS2X with a few extra improvements. (see next point)

  • Class loading: while class loading remains similar to SFS2X we have changed the way in which the system works internally to ensure no Extension library will conflict with SmartFoxServer's own dependencies. You can read more about this here.

  • Class and method name changes: while we have prioritized keeping the class and method names as close as possible to SFS2X, you may find some missing method or class names when converting an old Extension. For example SFSObject's putUtfString() has been renamed to putString(), since the 'utf' part is implicit (all strings in Java are UTF).

Broadly speaking we recommend leveraging your IDE to fix the occasional broken import or missing method, should you encounter one.

» Additional resources: